API
Technical Information

Description

Poker Mavens contains an Application Programming Interface (API) for communicating with the live game server from external programs, including scripting systems like PHP and ASP.NET. Commands can also be tested by hand via any web browser but note that this system is different from the Remote Administration system, which is designed for human interaction with your server. The interface described here is for computer to computer interaction.

To use this system you must have "Enable API" set to "Yes" in the server settings and your server must be started and online. It works by making an HTTP request to the file port of your server with /api appended to the end of the URL (or a custom path that you can change in the server settings). Parameters can be passed via GET (embedded in the URL) or via POST (embedded in the HTTP header). There are two parameters that must be included with each request: Password and Command. Password must be set to your API password and Command is set to one of the available commands as listed below. Other parameters may be required, depending on the particular command.

Warning: disclosing your API password (or your remote administration password) would give an attacker full access to your game server, including the modification or deletion of player accounts. Only allow your program or web script to execute on a computer that you that have control over. Otherwise the operator could use a packet sniffer program to see the password being sent in the outbound traffic.

Commands sent to the API will be recorded in the event logs if "Log API events" is set to "Yes" in the system settings. The IP address of the source is also recorded. Every command supports an optional "Log" parameter that you can use to append custom text to each log entry. However, if that Log parameter is set to "No" and "API Log Exemptions" is enabled in the system settings, then no entry will be made in the event log.

Example

For example, if your IP is 12.34.56.789, your file port is 8087, your API password is "banana", and you want to increment the current chip balance of a player named Aces123 by 1000 chips, then your program would make an HTTP request to:

http://12.34.56.789:8087/api

with parameters set via POST as:

Password=banana
Command=AccountsIncBalance
Player=Aces123
Amount=1000
Log=Give 1000 chips to Aces123

or via GET as:

http://12.34.56.789:8087/api?Password=banana&Command=AccountsIncBalance&Player=Aces123&Amount=1000&Log=Give 1000 chips to Aces123

The order and case of the parameters is not important but the first one must begin with a question mark and all remaining ones must be separated by an ampersand when using the GET method.

The server always responds with a block of text containing a "Result" parameter and possibly others depending on the particular command and if there were any errors. Result will either be set to Ok or Error. If there was an error then an Error parameter will be included with a description of the error. When there are multiple parameters returned, they are separated by a carriage return/line feed pair (ASCII 13 and 10). Using the example above, a typical response will look something like this:

Result=Ok
Balance=5000

And the entry into the Event Logs (with the optional Log parameter) would look something like this:

2008-07-20 17:06:29|API|AccountsIncBalance from 12.34.56.789 (Give 1000 chips to Aces123)

Or if there was an error:

Result=Error
Error=Unknown account

JSON Support

Beginning with version 4.20, you can get the return data in JSON format by including JSON=Yes in your POST or GET parameters. Then the API would return something like this:

{"Result":"Ok",Balance:5000}

or this:

{"Result":"Error","Error":"Unknown account"}

PHP Example (JSON method)

This function can be used in PHP from a web site to access the API and return a single object containing the results. This method requests the result in JSON format, which first became an option in version 4.20. For older versions, see the legacy method further below.

  $url = "http://127.0.0.1:8087/api";  // put your API path here
  $pw = "xxxxxxxxxx";                  // put your API password here

  function Poker_API($params)          // pass in parameters using an associative array
  {
    global $url, $pw;
    $params['Password'] = $pw;
    $params['JSON'] = 'Yes';
    $curl = curl_init($url);
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($params));
    curl_setopt($curl, CURLOPT_TIMEOUT, 30);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); 
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
    $response = curl_exec($curl);
    if (curl_errno($curl)) $obj = (object) array('Result' => 'Error', 'Error' => curl_error($curl)); 
    else if (empty($response)) $obj = (object) array('Result' => 'Error', 'Error' => 'Connection failed'); 
    else $obj = json_decode($response);
    curl_close($curl);
    return $obj;
  }

Using the data from the previous example, you would call it like this:

$params = array("Command" => "AccountsIncBalance", "Player" => "Aces123", "Amount" => "1000");
$api = Poker_API($params);

And then process the response like this:

if ($api -> Result == "Ok") echo "The chip balance is " . $api -> Balance;
else echo "Error: " . $api -> Error;

Other examples are available online.

PHP Example (legacy method)

This function can be used in PHP from a web site to access the API and return a regular or an associative array containing the results:

  function Poker_API($url, $params, $assoc)
  {
    $curl = curl_init($url);
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $params);
    curl_setopt($curl, CURLOPT_TIMEOUT, 30);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); 
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
    $response = trim(curl_exec($curl));
    if (curl_errno($curl)) $cerror = curl_error($curl); else $cerror = "";
    curl_close($curl);
    $api = Array();
    if ($assoc)  // associative array result
    {
      if ($cerror != "")
      {
        $api["Result"] = "Error";
        $api["Error"] = $cerror;
      }
      else if (empty($response))
      {
        $api["Result"] = "Error";
        $api["Error"] = "Connection failed";
      }
      else  
      {
        $paramlist = Explode("\r\n", $response);
        foreach ($paramlist as $param)
        {
          $namevalue = Explode("=", $param, 2);
          $api[$namevalue[0]] = $namevalue[1];
        }
      }
    }
    else  // regular array result
    {
      if ($cerror != "")
      {
        $api[] = "Result=Error"; 
        $api[] = "Error=" . $cerror; 
      }
      else if (empty($response))
      {
        $api[] = "Result=Error"; 
        $api[] = "Error=Connection failed"; 
      }
      else  
      {
        $paramlist = Explode("\r\n", $response);
        foreach ($paramlist as $param) $api[] = $param;
      }
    }
    return $api;
  }

Using the data from the previous example, you would call it like this:

$url = "http://12.34.56.789:8087/api";
$params = "Password=banana&Command=AccountsIncBalance&Player=Aces123&Amount=1000";
$api = Poker_API($url,$params,true);

And then process the response like this:

if ($api[Result] == "Ok") echo "The chip balance is " . $api[Balance];
else echo "Error: " . $api[Error];

Other examples are available online.

URL Encoding (legacy method)

Note: parameter encoding is handled for you automatically when using the JSON method (via the http_build_query function). The following only applies when using the legacy method or when manually calling the API with GET parameters.

Certain characters like "?", "&", "=", "%", "#", and several others are treated as control characters in URL strings. Therefore you must encode any parameter values that contain those characters using the form %xx where xx is the ASCII code of the character in hexadecimal format, in accordance with section 2.2 of RFC1738. For example, if you wanted to retrieve the tournament results for a tournament called "Rough&Ready", using the raw parameter of:

Tournament=Rough&Ready

would fail because the "&" would indicate the beginning of a new parameter. The ASCII code for "&" is 38 decimal or 26 hexadecimal so the proper encoding would be:

Tournament=Rough%26Ready

Most programming languages have built-in functions for encoding URL parameters. In PHP (for example), the function is urlencode(string) or rawurlencode(string).

Firewall

Some hosting services will have a default firewall setting that blocks connections to outbound ports other than 80 and 443, the standard HTTP/HTTPS ports. So if you can make a manual API connection in your web browser to port 8087 (or whatever File Port you have set) but get a "Connection failed" result when using scripted code, that firewall is likely the reason. Talk to your host provider (where the script is hosted) and see if they will open that port for outbound connections in your account.

Avatars

Although not technically part of the API, the server provides access to the communal avatar graphic and individual custom player avatars so that you can display them for the purposes of creating or editing player accounts. No API password is required so this can be safely used in public links on a web page. To pull the whole communal avatar graphic, simply reference a link like this (with your own IP address or domain name):

http://12.34.56.789:8087/Image?Name=Avatars

To isolate a single avatar in the horizontal strip, use a DIV element set to a width and height of 32 pixels (48 pixels in versions 2 to 4) and then use the CSS background-position property to specify a horizontal offset. This will be a negative number and a multiple of 32 pixels such that the first avatar will have a background-position of "0px 0px", the second will be "-32px 0px", the third will be "-64px 0px", etc. This example will display the third one:

<!DOCTYPE html>
<html>
<head>
<style type="text/css">
  #avatar { 
            width: 32px; 
            height: 32px; 
            background-image: url("http://12.34.56.789:8087/Image?Name=Avatars");
            background-repeat: no-repeat;
            background-position: -64px 0px; 
          }
</style>
</head>
<body>
  <div id="avatar"></div>
</body>
</html>

For the custom player avatars (not part of the communal set), you just need a simple link with the player's name as one of the parameters:

http://12.34.56.789:8087/Avatar?Player=AceMan

API Command List

As documented below, there are over 60 API commands available in 7 categories:

Account Commands

AccountsAdd - adds a new player account. The player's chip balance will be set automatically to the default "Starting balance" specified in the system settings and returned as a "Balance" parameter in the response. Specify the following parameters:

AccountsDecBalance - decrements the account balance of a player. This command does not check to see if you have "Allow negative balance" turned on or not in the account settings. An "Amount" parameter is included in the response that specifies the number of chips that were actually subtracted. A "Balance" parameter is returned with the player's new chip balance. This command is safe to use even while the player is logged in and playing.

AccountsDelete - deletes the specified account. Player is the only required parameter.

AccountsEdit - change one or more settings in a player account. Player is the only required parameter and cannot be changed itself. Include other parameters only for the items you want to change. Parameters not included will retain their current values.

AccountsGet - retrieves settings for the account specified by the Player parameter. In additional, a non-blank SessionID will be returned if the player is currently logged in. If they are seated at any ring games, the total amount of chips they have in play will be returned with the RingChips parameter. If they are in the waiting list for any tournaments that have not yet started, the total buy-in and entry fee amounts will be returned with the RegChips parameter. A typical response will look something like this (JSON format):

{"Result":"Ok","Player":"Aces123","Title":"","Level":"","RealName":"John","Location":"Texas","Email":"[email protected]","ValCode":"Balance":5000,"LastReset":"2008-7-01 12:13:42","Avatar":39,"AvatarFile":"","Logins":67,"FirstLogin":"2008-06-09 13:14:06","LastLogin":"2008-07-22 21:07:12","Gender":"Male","Permissions":"","Tickets":"","ChipsTransfer":"Yes","ChipsAccept":"Yes","Chat":"0000-00-00 00:00","ChatColor1":"","ChatColor2":"","Custom":"","Note":"","ERake":0,"PRake":0,"TFees":0,"RingChips":1234,"RegChips":1500,"SessionID":"00000001"}

or in legacy format:

Result=Ok
Player=Aces123
Title=
Level=
RealName=John
Location=Texas
[email protected]
ValCode=
Balance=5000
LastReset=2008-07-01 12:13:42
Avatar=39
AvatarFile=
Logins=67
FirstLogin=2008-06-09 13:14:06
LastLogin=2008-07-22 21:07:12
Gender=Male
Permissions=
Tickets=
ChipsTransfer=Yes
ChipsAccept=Yes
Chat=0000-00-00 00:00
ChatColor1=
ChatColor2=
Custom=
Note=
ERake=0
PRake=0
TFees=0
RingChips=1234
RegChips=1500
SessionID=00000001

AccountsIncBalance - increments the account balance of a player. Use a Player parameter to specify the player's name and an Amount parameter to specify the number of chips to add to the account. A "Balance" parameter is returned in the result indicating the player's new chip balance. This command is safe to use even while the player is logged in and playing.

AccountsList - retrieves a list of player accounts. Calling this with no parameters will just return the number of accounts. Set an optional Players field with a comma separated list (no spaces) of player names. Leave this field blank to retrieve all player accounts. Set the Fields parameter to a comma separated list (no spaces) of field names that you want returned. You may choose any combination of these fields:

Player, Title, Level, RealName, Location, Email, ValCode, Balance, LastReset, Avatar, AvatarFile, Logins, FirstLogin, LastLogin, Gender, Permissions, Tickets, ChipsTransfer, ChipsAccept, Chat, ChatColor1, ChatColor2, Custom, Note, ERake, PRake, TFees, RingChips, RegChips, SessionID

A sample response with "Fields=Player,Balance" may look something like this (JSON format):

{"Result":"Ok","Accounts":3,"Player":["Aces123","BoneCrusher","David"],"Balance":[2345,3470,1000]}

or in legacy format:

Result=Ok
Accounts=3
Player1=Aces123
Balance1=2345
Player2=BoneCrusher
Balance2=3470
Player3=David
Balance3=1000

AccountsPassword - verifies a player's password. Use a Player parameter to specify a player's name and a PW parameter for the player's password. The password will be hashed by the server and compared to the stored hash. If the hashes match the result will be (JSON format):

{"Result":"Ok","Verified":"Yes"}

or in legacy format:

Result=Ok
Verified=Yes

AccountsPermission - add, remove, or query individual permissions for a specified player. Use a Player parameter to specify the account, a Permission parameter for the permission token, and an Action parameter set to either "Add", "Remove", or "Query". The Add and Remove actions will return a Result = Ok response if successful. The Query action will return a Yes or No response indicating if the player has the specified permission (JSON format):

{"Result":"Ok","Query":"Yes"}

or in legacy format:

Result=Ok
Query=Yes

Note that if you want to get or replace a player's full list of permissions, use the AccountsGet and AccountsEdit commands.

AccountsSearch- returns the list of ring games and tournaments for a player specified by the Player parameter where they are currently seated or in the waiting list. A typical response will look something like this (JSON format):

{"Result":"Ok","Player":"Aces123","LoggedIn":"Yes","RingWaitCount":1,"RingPlayCount":2,"TrnyRegCount":1,"TrnyPlayCount":2,"RingWaitName":["Ring Game #01"],"RingPlayName":["Ring Game #02","Ring Game #03"],"RingPlayChips":[1250, 1500],"TrnyRegName":["Tournament #01"],"TrnyRegChips":[1500],"TrnyPlayName":["Tournament #02", "Tournament #03"],"TrnyPlayTable":[2,6]}

or in legacy format:

Result=Ok
Player=Aces123
LoggedIn=Yes
RingWaitCount=1
RingPlayCount=2
TrnyRegCount=1
TrnyPlayCount=2
RingWaitName1=Ring Game #01
RingPlayName1=Ring Game #02
RingPlayName2=Ring Game #03
RingPlayChips1=1250
RingPlayChips2=1500
TrnyRegName1=Tournament #01
TrnyRegChips1=1500
TrnyPlayName1=Tournament #02
TrnyPlayName2=Tournament #03
TrnyPlayTable1=2
TrnyPlayTable2=6

AccountsSessionKey - creates a random 80-bit session key for a player specified by the Player parameter. The session key serves as a one-time-only password for an automated login. See the Technical Information/Startup Parameters topic for instructions on using session keys. A typical response will look something like this (JSON format):

{"Result":"Ok","Player":"Aces123","SessionKey":"1234567890ABCDEF1234"}

or in legacy format:

Result=Ok
Player=Aces123
SessionKey=1234567890ABCDEF1234

AccountsTicket - add, remove, or query individual tournament tickets for a specified player. Use a Player parameter to specify the account, a Ticket parameter for the ticket token, and an Action parameter set to either "Add", "Remove", or "Query". The Add and Remove actions will return a Result = Ok response if successful. The Query action will return a Yes or No response (and a Count parameter beginning with version 5.09) indicating if the player has the specified ticket (JSON format):

{"Result":"Ok","Query":"Yes","Count":1}

or in legacy format:

Result=Ok
Query=Yes
Count=1

Note that if you want to get or replace a player's full list of tickets, use the AccountsGet and AccountsEdit commands.

Blacklist Commands

BlacklistAdd - add a new entry into the player blacklist. You must specify at least one parameter in the group of Player, IP, and PC.

BlacklistDelete - deletes an item from the blacklist. Specify the item with an ID parameter.

BlacklistEdit - edit one or more fields for a blacklist item, as specified with an ID parameter. Other than the ID, only include parameters for the fields you want to change, otherwise the field will retain its current value.

BlacklistGet - retrieves the fields for the specified blacklist item, as determined by an ID parameter. A sample response may look something like this (JSON format):

{"Result":"Ok","ID":"00000001","Date":"2008-06-20 08:17:01","Player":"DeathBot","IP":"12.34.56.789","PC":"12345678","Match":"Any","Note":"Abusive player"}

or in legacy format:

Result=Ok
ID=00000001
Date=2008-06-20 08:17:01
Player=DeathBot
IP=12.34.56.789
PC=12345678
Match=Any
Note=Abusive player

BlacklistList - retrieves a list of all blacklist entries. Calling this with no parameters will just return a count of entries. Set the Fields parameter to a comma separated list of field names that you want returned. Do not include spaces in the list. You may choose any combination of these fields:

ID, Date, Player, IP, PC, Match, Note

A sample response with "Fields=ID,Player,IP" may look something like this (JSON format):

{"Result":"Ok","Count":2,"ID":["00000001","00000002"],"Player":["DeathBot","TroubleMaker"],"IP":["12.34.56.789","98.76.54.321"]}

or in legacy format:

Result=Ok
Count=2
ID1=00000001
Player1=DeathBot
IP1=12.34.56.789
ID2=00000002
Player2=TroubleMaker
IP2=98.76.54.321

Connection Commands

ConnectionsGet - retrieves values for the connection specified by the SessionID parameter. A typical response will look something like this (JSON format):

{"Result":"Ok","SessionID":"00000001","Status":"Ok","Player":"Aces123","PC":"12345678","IP":"12.34.56.789","Proxy":"","Connect":"2015-01-22 14:07:23","Login":"2015-01-22 14:24:56","LastAction":"2015-01-22 14:52:01","PacketsIn":123,"PacketsOut":890}

or in legacy format:

Result=Ok
SessionID=00000001
Status=Ok
Player=Aces123
PC=12345678
IP=12.34.56.789
Proxy=
Connect=2015-01-22 14:07:23
Login=2015-01-22 14:24:56
LastAction=2015-01-22 14:52:01
PacketsIn=123
PacketsOut=890

ConnectionsList - retrieves the list of all current connections. Calling this with no parameters will just return the number of connections. Set the Fields parameter to a comma separated list of field names that you want returned. Do not include spaces in the list. You may choose any combination of these fields:

SessionID, Status, Player, PC, IP, Proxy, Connect, Login, LastAction, PacketsIn, PacketsOut

A sample response with "Fields=Player,IP" may look something like this (JSON format):

{"Result":"Ok","Connections":2,"Player":["Aces123","BoneCrusher"],"IP":["12.34.56.789","98.76.54.321"]}

or in legacy format:

Result=Ok
Connections=2
Player1=Aces123
IP1=12.34.56.789
Player2=BoneCrusher
IP2=98.76.54.321

ConnectionsMessage - sends a popup message to the person at the specified SessionID parameter with the message text specified in the Message parameter. Use an asterisk (*) as the SessionID to send the message to all connections.

ConnectionsTerminate - terminates the connection at the specified SessionID parameter.

Log Commands

LogsAddEvent - adds a line to the Event Log without performing any other command. Use the Log parameter to append custom text to the entry. Note that this Log parameter is an option with all of the other API commands, also.

LogsCallback - call without any parameters to retrieve a list of dates where a callback log file was created. This command was added in version 5.17. Example output will look something like this (JSON format):

{"Result":"Ok","Files":3,"Date":["2017-09-01","2017-09-06","2017-09-07"]}

or in legacy format:

Result=Ok
Files=3
Date1=2017-09-01
Date2=2017-09-06
Date3=2017-09-07

Call with a Date parameter in the format of yyyy-mm-dd to retrieve the contents of a callback log file. Use the optional Start and Count parameters to specify a range of lines to retrieve. The first line number is 0. A Start value of -1 will retrieve lines from the end of the file. A Count value of 0 will retrieve the remaining lines from the starting point. Each line in the callback log is a JSON object. Example output will look something like this (JSON format):

{"Result":"Ok","Start":3,"Count":3,"Data":[{"Event":"LobbyChat","Player":"pm2","Title":"","Chat":"howdy","Time":"2017-09-07 15:24:52"},{"Event":"Balance","Player":"pm1","Change":"-1200","Balance":"96280","Source":"Ring Game #06","Time":"2017-09-07 15:25:02"},{"Event":"RingGameJoin","Name":"Ring Game #06","Player":"pm1","Amount":"1200","Time":"2017-09-07 15:25:03"}]}

or in legacy format:

Result=Ok
Start=3
Count=3
{"Event":"LobbyChat","Player":"pm2","Title":"","Chat":"howdy","Time":"2017-09-07 15:24:52"}
{"Event":"Balance","Player":"pm1","Change":"-1200","Balance":"96280","Source":"Ring Game #06","Time":"2017-09-07 15:25:02"}
{"Event":"RingGameJoin","Name":"Ring Game #06","Player":"pm1","Amount":"1200","Time":"2017-09-07 15:25:03"}

LogsError - call without any parameters to retrieve a list of dates where an error log file was created. Example output will look something like this (JSON format):

{"Result":"Ok","Files":3,"Date":["2015-02-01","2015-02-05","2015-02-06"]}

or in legacy format:

Result=Ok
Files=3
Date1=2015-02-01
Date2=2015-02-05
Date3=2015-02-06

Call with a Date parameter in the format of yyyy-mm-dd to retrieve the contents of an error log file. Beginning with version 5.17, use the optional Start and Count parameters to specify a range of lines to retrieve. The first line number is 0. A Start value of -1 will retrieve lines from the end of the file. A Count value of 0 will retrieve the remaining lines from the starting point. Example output will look something like this (JSON format):

{"Result":"Ok","Start":0,"Count":2,"Data":["2015-02-06 13:21:42|Remote admin whitelist denial for 127.0.0.1","2015-02-06 13:29:02|API whitelist denial for 192.168.1.100"]}

or in legacy format:

Result=Ok
Start=0
Count=2
2015-02-06 13:21:42|Remote admin whitelist denial for 127.0.0.1
2015-02-06 13:29:02|API whitelist denial for 192.168.1.100

LogsEvent - call without any parameters to retrieve a list of dates where an event log file was created. Example output will look something like this (JSON format):

{"Result":"Ok","Files":3,"Date":["2015-02-01","2015-02-05","2015-02-06"]}

or in legacy format:

Result=Ok
Files=3
Date1=2015-02-01
Date2=2015-02-05
Date3=2015-02-06

Call with a Date parameter in the format of yyyy-mm-dd to retrieve the contents of an event log file. Beginning with version 5.17, use the optional Start and Count parameters to specify a range of lines to retrieve. The first line number is 0. A Start value of -1 will retrieve lines from the end of the file. A Count value of 0 will retrieve the remaining lines from the starting point. Example output will look something like this (JSON format):

{"Result":"Ok","Start":0,"Count":3,"Data":["2015-02-10 18:36:55|System|Game server started","2015-02-10 18:36:55|Table|Ring Game #1 opened","2015-02-10 18:36:55|Table|Tournament #1 opened"]}

or in legacy format:

Result=Ok
Start=0
Count=3
2015-02-10 18:36:55|System|Game server started
2015-02-10 18:36:55|Table|Ring Game #1 opened
2015-02-10 18:36:55|Table|Tournament #1 opened

LogsHandHistory - call without any parameters to retrieve a list of dates and table names where a hand history file was created. Example output will look something like this (JSON format):

{"Result":"Ok","Files":2,"Date":["2015-02-01","2015-02-05"],"Name":["Ring Game #1","Tournament #3 - Table 1"]}

or in legacy format:

Result=Ok
Files=2
Date1=2015-02-01
Name1=Ring Game #1
Date2=2015-02-05
Name2=Tournament #3 - Table 1

Call with a Date parameter in the format of yyyy-mm-dd and a Name parameter to retrieve the contents of a hand history file. Beginning with version 5.17, use the optional Start and Count parameters to specify a range of lines to retrieve. The first line number is 0. A Start value of -1 will retrieve lines from the end of the file. A Count value of 0 will retrieve the remaining lines from the starting point. Example output will look something like this (JSON format):

{"Result":"Ok","Start":0,"Count":13,"Data":["Hand #3859-1 - 2015-02-18 18:31:12","Game: No Limit Hold'em (500 - 2000) - Blinds 10/20","Site: Briggs Softworks","Table: Ring Game #1","Seat 4: pm2 (2000)","Seat 9: pm1 (1180)","pm2 has the dealer button","pm2 posts small blind 10","pm1 posts big blind 20","** Hole Cards **","pm2 folds","pm1 refunded 10","pm1 wins Pot (20)"]}

or in legacy format:

Result=Ok
Start=0
Count=13
Hand #3859-1 - 2015-02-18 18:31:12
Game: No Limit Hold'em (500 - 2000) - Blinds 10/20
Site: Briggs Softworks
Table: Ring Game #1
Seat 4: pm2 (2000)
Seat 9: pm1 (1180)
pm2 has the dealer button
pm2 posts small blind 10
pm1 posts big blind 20
** Hole Cards **
pm2 folds
pm1 refunded 10
pm1 wins Pot (20)

Call with a Hand parameter (indicating the hand number) to retrieve the hand history of a single hand. Leave the other parameters blank when using the Hand parameter. The server caches the last 100 hands played so the specified hand must still be in the cache or an error will be returned. Although the full hand number can be specified, only the first portion (left of the dash) is required. Use the Hand callback event system to get notified when a new hand is available.

LogsLobbyChat - call without any parameters to retrieve a list of dates where a lobby chat log file was created. Example output will look something like this (JSON format):

{"Result":"Ok","Files":3,"Date":["2015-02-01","2015-02-05","2015-02-06"]}

or in legacy format:

Result=Ok
Files=3
Date1=2015-02-01
Date2=2015-02-05
Date3=2015-02-06

Call with a Date parameter in the format of yyyy-mm-dd to retrieve the contents of a lobby chat log file. Beginning with version 5.17, use the optional Start and Count parameters to specify a range of lines to retrieve. The first line number is 0. A Start value of -1 will retrieve lines from the end of the file. A Count value of 0 will retrieve the remaining lines from the starting point. Example output will look something like this (JSON format):

{"Result":"Ok","Start":0,"Count":2,"Data":["2015-02-10 18:35:55 Alice: are you going to play in the tournament?","2015-02-10 18:36:14 Bob: yeah, see you there"]}

or in legacy format:

Result=Ok
Start=0
Count=2
2015-02-10 18:35:55 Alice: are you going to play in the tournament?
2015-02-10 18:36:14 Bob: yeah, see you there

Ring Game Commands

RingGamesAdd - adds a new ring game to the system. The newly created game will be in an offline state. Specify the following parameters:

RingGamesDelete - deletes the ring game specified by the Name parameter. The game must already be in an offline state before it can be deleted.

RingGamesEdit - edits one or more properties of an offline ring game specified by the Name parameter. Fields not specified will retain their current value.

RingGamesGet - retrieve the settings for the ring game specified by the Name parameter. A sample response will look something like this (JSON format):

{"Result":"Ok",
"Name":"Ring Game #1",
"Status":"Playing: 9",
"Description":"",
"Auto":"Yes",
"Game":"No Limit Hold'em",
"MixedList":"",
"PW":"",
"Private":"No",
"PermPlay":"",
"PermObserve":"",
"PermPlayerChat":"",
"PermObserverChat":"",
"SuspendChatAllIn":"No",
"Seats":9,
"SmallestChip":1,
"BuyInMin":500,
"BuyInMax":2500,
"BuyInDef":1500,
"RakePercent":0,
"RakeCap":0,
"TurnClock":30,
"TurnWarning":10,
"TimeBank":60,
"BankSync":"Yes",
"BankReset":0,
"DisProtect":"Yes",
"SmallBlind":10,
"BigBlind":20,
"AllowStraddle":"No",
"SmallBet":0,
"BigBet":0,
"Ante":0,
"AnteAll":"No",
"BringIn":0,
"DupeIPs":"No",
"RatholeMinutes":0,
"SitoutMinutes":10,
"SitoutRelaxed":"No"}

or in legacy format:

Result=Ok
Name=Ring Game #1
Status=Playing: 9
Description=
Auto=Yes
Game=No Limit Hold'em
MixedList=
PW=
Private=No
PermPlay=
PermObserve=
PermPlayerChat=
PermObserverChat=
SuspendChatAllIn=No
Seats=9
SmallestChip=1
BuyInMin=500
BuyInMax=2500
BuyInDef=1500
RakePercent=0
RakeCap=0
TurnClock=30
TurnWarning=10
TimeBank=60
BankSync=Yes
BankReset=0
DisProtect=Yes
SmallBlind=10
BigBlind=20
AllowStraddle=No
SmallBet=0
BigBet=0
Ante=0
AnteAll=No
BringIn=0
DupeIPs=No
RatholeMinutes=0
SitoutMinutes=10
SitoutRelaxed=No

RingGamesList - retrieves the list of all ring games. Calling this with no parameters will just return the number of ring games. Set the Fields parameter to a comma separated list of field names that you want returned. Do not include spaces in the list. You may choose any combination of these fields:

Name, Status, Description, Auto, Game, MixedList, PW, Private, PermPlay, PermObserve, PermPlayerChat, PermObserverChat, SuspendChatAllIn, Seats, SmallestChip, BuyInMin, BuyInMax, BuyInDef, RakePercent, RakeCap, TurnClock, TurnWarning, TimeBank, BankSync, BankReset, DisProtect, SmallBlind, BigBlind, AllowStraddle, SmallBet, BigBet, Ante, AnteAll, BringIn, DupeIPs, RatholeMinutes, SitoutMinutes, SitoutRelaxed

A sample response with "Fields=Name,Game" may look something like this (JSON format):

{"Result":"Ok","RingGames":3,"Name":["Ring Game #1","Ring Game #2","Ring Game #3"],"Game":["No Limit Hold'em","Pot Limit Hold'em","Limit Hold'em"]}

or in legacy format:

Result=Ok
RingGames=3
Name1=Ring Game #1
Game1=No Limit Hold'em
Name2=Ring Game #2
Game2=Pot Limit Hold'em
Name3=Ring Game #3
Game3=Limit Hold'em

RingGamesMessage - sends an Administrator message to the chat box for the ring game specified by the Name parameter. Put the text of the message in the Message parameter. Use an asterisk (*) as the Name parameter to send the message to all ring game tables.

RingGamesOffline - closes the ring game specified by the Name parameter and puts it in an offline state. Set an optional Now parameter to "Yes" to close the table immediately. Otherwise, the table will close when the current hand is finished.

RingGamesOnline - puts the ring game specified by the Name parameter into an online state, making it available for play.

RingGamesOpen - opens a ring game table in the player client for the specified player (who must already be logged in). Specify the ring game by the Name parameter and the player by the Player parameter.

RingGamesPause - pauses an online ring game specified by the Name parameter. Set parameter Now to "Yes" (the default) to pause the table immediately or to "No" to pause it once the current hand completes.

RingGamesPlaying - retrieves the list of seated players for the ring game specified by the Name parameter. The Away field shows the number of minutes that a player has been sitting out. A sample response may look something like this (JSON format):

{"Result":"Ok","Count":2,"Player":["Aces123","BoneCrusher"],"Seat":[2,7],"Chips":[430,650],"Net":[-70,150],"Away":[0,0]}

or in legacy format:

Result=Ok
Player1=Aces123
Seat1=2
Chips1=430
Net1=-70
Away1=0
Player2=BoneCrusher
Seat2=7
Chips2=650
Net2=150
Away2=0
Count=2

RingGamesResume - resumes a paused ring game specified by the Name parameter.

RingGamesWaiting - retrieves the list of players in the waiting list for the ring game specified by the Name parameter. A sample response will look something like this (JSON format):

{"Result":"Ok","Count":3,"Wait":["Aces123","BoneCrusher","Wizard"]}

or in legacy format:

Result=Ok
Count=3
Wait1=Aces123
Wait2=BoneCrusher
Wait3=Wizard

System Commands

SystemAccount - This command allows you to get or change the balance of a house account, specified by the Account parameter ("Master", "Ring", "Rake", "Tourney", or "EntryFee"). Set an Action parameter ("Set", "Inc", or "Dec") along with an Amount parameter to set, increment, or decrement the specified account by that amount. To retrieve the current balance, set Action to "Get" (Amount parameter not used in this case). The result will contain a Balance parameter indicating the new balance and a Change parameter indicating the difference between the previous balance and the new balance. In JSON format, a typical result will look something like this:

{"Result":"Ok","Balance":123456,"Change":-1000}

or in legacy format:

Result=Ok
Balance=123456
Change=-1000

SystemBalance - This command returns the current balance of all house accounts plus the sum total of all player accounts. A House parameter is also returned with the total of all house accounts (not including the Players account). There are no calling parameters for this command. A typical result will look like this in JSON format:

{"Result":"Ok","Master":123456,"Ring":1000,"Rake":10,"Tourney":2000,"EntryFee":20,"House":126486,"Players":123456789}

or in legacy format:

Result=Ok
Master=123456
Ring=1000
Rake=10
Tourney=2000
EntryFee=20
House=126486
Players=123456789

SystemGet - gets the value for the specified Property parameter. For example, if you specified "FilePort" for the Property, a typical response would look like this (JSON format):

{"Result":"Ok","Value":"8087"}

or in legacy format:

Result=Ok
Value=8087

Beginning with version 5.11, you can specify an asterisk (*) for the Property parameter and the values of all system properties will be returned.

The list of available Property names are as follows:

SystemSet - sets the Value of the specified system Property. For example, to turn off the login chime, set the Property parameter to "LoginChime" and the Value parameter to "No". See the SystemGet command above for a list of all available system property names. Properties marked as "read-only" cannot be changed while the game server is online.

SystemLobbyMessage - sends a message to the Lobby chat box. Put the text of the message in the Message parameter. Specify a optional Player parameter to send the message from a specific player account (which must exist but does not need to be logged in) or leave blank to send the message from the Administrator.

SystemReboot - reboots the computer immediately. This command does not attempt an orderly shutdown of active tables.

SystemStats - returns the following parameters related to the current server statistics:

Tournament Commands

TournamentsAdd - adds a new tournament to the system. The newly created game will be in an offline state. Specify the following parameters:

TournamentsDelete - deletes the tournament specified by the Name parameter. The game must already be in an offline state before it can be deleted.

TournamentsEdit - edits one or more properties of an offline tournament specified by the Name parameter. Fields not specified will retain their current value.

TournamentsGet - retrieve the settings for the tournament specified by the Name parameter. A sample response will look something like this (JSON format):

{"Result":"Ok",
"Name":"Tournament #1",
"Status":"Playing: 6 of 9",
"Description":"",
"Auto":"Yes",
"Game":"No Limit Hold'em",
"MixedList":"",
"Shootout":"No",
"PW":"",
"Private":"No",
"PermRegister":"",
"PermUnregister":"",
"PermObserve":"",
"PermPlayerChat":"",
"PermObserverChat":"",
"SuspendChatAllIn":"No",
"Tables":1,
"Seats":9,
"StartFull":"Yes",
"StartMin":1,
"StartCode":0,
"StartTime":"0000-00-00 00:00",
"RegMinutes":0,
"LateRegMinutes":0,
"MinPlayers":2,
"RecurMinutes":0,
"ResetSeconds":30,
"NoShowMinutes":0,
"BuyIn":1500,
"EntryFee":0,
"Ticket":"",
"TicketRequired":"No",
"TicketFunded":"No",
"PrizeBonus":0,
"MultiplyBonus":"No",
"Chips":1500,
"AddOnChips":0,
"TurnClock":30,
"TurnWarning":10,
"TimeBank":60,
"BankSync":"Yes",
"BankReset":0,
"DisProtect":"Yes",
"Level":10,
"RebuyLevels":0,
"Threshold":1500,
"MaxRebuys":0,
"RebuyCost":0,
"RebuyFee":0,
"BreakTime":0,
"BreakLevels":0,
"StopOnChop":"No",
"BringInPercent": 30,
"Blinds":"10/20/0, 15/30/0, 25/50/0, 50/100/0, 75/150/0, 100/200/0, 100/200/25, 200/400/25, 300/600/50, 400/800/50, 600/1200/75, 800/1600/75, 1000/2000/100, 1500/3000/150, 2000/4000/200, 3000/6000/300, 4000/8000/400",
"Payout":"2-4, 100.00|5-7, 65.00, 35.00|8-10, 50.00, 30.00, 20.00",
"PayoutTickets":"",
"UnregLogout":"No"}

or in legacy format:

Result=Ok
Name=Tournament #1
Status=Playing: 6 of 9
Description=
Auto=Yes
Game=No Limit Hold'em
MixedList=
Shootout=No
PW=
Private=No
PermRegister=
PermUnregister=
PermObserve=
PermPlayerChat=
PermObserverChat=
SuspendChatAllIn=No
Tables=1
Seats=9
StartFull=Yes
StartMin=1
StartCode=0
StartTime=0000-00-00 00:00
RegMinutes=0
LateRegMinutes=0
MinPlayers=2
RecurMinutes=0
ResetSeconds=30
NoShowMinutes=0
BuyIn=1500
EntryFee=0
Ticket=
TicketRequired=No
TicketFunded=No
PrizeBonus=0
MultiplyBonus=No
Chips=1500
AddOnChips=0
TurnClock=30
TurnWarning=10
TimeBank=60
BankSync=Yes
BankReset=0
DisProtect=Yes
Level=10
RebuyLevels=0
Threshold=1500
MaxRebuys=0
RebuyCost=0
RebuyFee=0
BreakTime=0
BreakLevels=0
StopOnChop=No
BringInPercent=30
Blinds=10/20/0, 15/30/0, 25/50/0, 50/100/0, 75/150/0, 100/200/0, 100/200/25, 200/400/25, 300/600/50, 400/800/50, 600/1200/75, 800/1600/75, 1000/2000/100, 1500/3000/150, 2000/4000/200, 3000/6000/300, 4000/8000/400
Payout=2-4, 100.00|5-7, 65.00, 35.00|8-10, 50.00, 30.00, 20.00
PayoutTickets=
UnregLogout=No

TournamentsList - retrieves the list of all tournaments. Calling this with no parameters will just return the number of tournaments. Set the Fields parameter to a comma separated list of field names that you want returned. Do not include spaces in the list. You may choose any combination of these fields:

Name, Status, Description, Auto, Game, MixedList, Shootout, PW, Private, PermRegister, PermUnregister, PermObserve, PermPlayerChat, PermObserverChat, SuspendChatAllIn, Tables, Seats, StartFull, StartMin, StartCode, StartTime, RegMinutes, LateRegMinutes, MinPlayers, RecurMinutes, ResetSeconds, NoShowMinutes, BuyIn, EntryFee, Ticket, TicketRequired, TicketFunded, PrizeBonus, MultiplyBonus, Chips, AddOnChips, TurnClock, TurnWarning, TimeBank, BankSync, BankReset, DisProtect, Level, RebuyLevels, Threshold, MaxRebuys, RebuyCost, RebuyFee, BreakTime, BreakLevels, StopOnChop, BringInPercent, Blinds, Payout, PayoutTickets, UnregLogout

A sample response with "Fields=Name,Game" may look something like this (JSON format):

{"Result":"Ok","Tournaments":3,"Name":["Tournament #1","Tournament #2","Tournament #3"],"Game":["Limit Hold'em","Pot Limit Hold'em","No Limit Hold'em"]}

or in legacy format:

Result=Ok
Tournaments=3
Name1=Tournament #1
Game1=Limit Hold'em
Name2=Tournament #2
Game2=Pot Limit Hold'em
Name3=Tournament #3
Game3=No Limit Hold'em

TournamentsMessage - sends an Administrator message to the chat box for all tables in the tournament specified by the Name parameter. Put the text of the message in the Message parameter. Use an asterisk (*) as the Name parameter to send the message to all tournaments.

TournamentsOffline - closes the tournament specified by the Name parameter and puts it in an offline state. Set an optional Now parameter to "Yes" to close the tournament immediately. Otherwise, the tournament will close after it finishes.

TournamentsOnline - puts the tournament specified by the Name parameter into an online state, making it available for play.

TournamentsOpen - opens a tournament table in the player client for the specified player (who must already be logged in). Specify the tournament by the Name parameter, the table number by the Table parameter (defaults to 1), and the player by the Player parameter.

TournamentsPause - pauses a running tournament specified by the Name parameter. Set parameter Now to "Yes" (the default) to pause all tables immediately or to "No" to pause each table individually once the current hand completes.

TournamentsPlaying - retrieves the list of seated and finished players for the tournament specified by the Name parameter. The tournament number and running time are also included. The Away field shows the number of minutes that a player has been sitting out. A sample response may look something like this (JSON format):

{"Result":"Ok","Number":123456,"Time":"0:32","Count":3,"Player":["Aces123","BoneCrusher","Dave"],"Table":[1,1,0],"Seat":[1,4,0],"Chips":["1650","1475","Finished"],"Rebuys":[0,0,0],"AddOns":[0,0,0],"Rank":[1,2,3],"NoShow":["No","No","No"],"Away":[0,0,1]}

or in legacy format:

Result=Ok
Number=123456
Time=0:32
Player1=Aces123
Table1=1
Seat1=1
Chips1=1650
Rebuys1=0
AddOns1=0
Rank1=1
NoShow1=No
Away1=0
Player2=BoneCrusher
Table2=1
Seat2=4
Chips2=1475
Rebuys2=0
AddOns2=0
Rank2=2
NoShow2=No
Away2=0
Player3=Dave
Table3=0
Seat3=0
Chips3=Finished
Rebuys3=0
AddOns3=0
Rank3=3
NoShow3=No
Away3=1
Count=3

TournamentsRegister - registers a player specified by the Player parameter for the tournament specified by the Name parameter and automatically deducts the applicable buy-in from their account. The player does not have to be logged in. Use the optional Negative parameter to bypass the system "Allow negative balance" setting. Set to "Allow" to allow the player's balance to go to a negative balance if they do not have enough chips to meet the buy-in price or to "Skip" to deny the registration in that case. Leave this parameter blank to obey the system setting.

TournamentsRemoveNoShows - removes all "no-show" players (never clicked their Ready button) from a running tournament specified by the Name parameter. Their buyin/entry fees are removed from the prizepool and added back to their accounts. No-shows can be removed up to the point of payout distribution.

TournamentsResults - call without any parameters to retrieve a list of dates and tournament names where a tournament results file was created. Example output will look something like this (JSON format):

{"Result":"Ok","Files":2,"Date":["2015-03-01","2015-03-05"],"Name":["Tournament #2","Tournament #5"]}

or in legacy format:

Result=Ok
Files=2
Date1=2015-03-01
Name1=Tournament #2
Date2=2015-03-05
Name2=Tournament #5

Call with a Date parameter in the format of yyyy-mm-dd and a Name parameter to retrieve the contents of a tournament results file. Example output will look something like this (JSON format):

{"Results":"Ok","Data":["Tournament=Tournament #1","Number=39","BuyIn=1500+0","PrizeBonus=0","MultiplyBonus=No","Entrants=2","Late=0","Removed=0","Rebuys=0","AddOns=0","RebuyCost=0+0","NetBonus=0","StopOnChop=No","Start=2015-07-12 13:41:21","Place2=BoneCrusher (0)","Place1=Aces123 (3000)","Stop=2015-07-12 13:42:04","","Tournament=Tournament #1","Number=40","BuyIn=1500+0","PrizeBonus=0","MultiplyBonus=No","Entrants=3","Late=0","Removed=0","Rebuys=1","AddOns=1","RebuyCost=1500+0","NetBonus=0","StopOnChop=No","Start=2015-07-12  7:11:26","Place3=DeathBot (0) Rebuys:1 AddOn:Yes","Place2=Aces123 (0) Rebuys:0 AddOn:No","Place1=BoneCrusher (7500) Rebuys:0 AddOn:No","Stop=2015-07-12 17:12:08"]}

or in legacy format:

Results=Ok
Tournament=Tournament #1
Number=39
BuyIn=1500+0
PrizeBonus=0
MultiplyBonus=No
Entrants=2
Late=0
Removed=0
Rebuys=0
AddOns=0
RebuyCost=0+0
NetBonus=0
StopOnChop=No
Start=2015-07-12 13:41:21
Place2=BoneCrusher (0)
Place1=Aces123 (3000)
Stop=2015-07-12 13:42:04

Tournament=Tournament #1
Number=40
BuyIn=1500+0
PrizeBonus=0
MultiplyBonus=No
Entrants=3
Late=0
Removed=0
Rebuys=1
AddOns=1
RebuyCost=1500+0
NetBonus=0
StopOnChop=No
Start=2015-07-12 17:11:26
Place3=DeathBot (0) Rebuys:1 AddOn:Yes
Place2=Aces123 (0) Rebuys:0 AddOn:No
Place1=BoneCrusher (7500) Rebuys:0 AddOn:No
Stop=2015-07-12 17:12:08

TournamentsResume - resumes a paused tournament specified by the Name parameter.

TournamentsStart - manually starts the tournament specified by the Name parameter. There must be at least two players registered to start a tournament.

TournamentsStats - retrieves basic statistics on a running tournament specified by the Name parameter. The tournament number and running time are also included. The Time parameter will be blank if the tournament is not currently running. A sample response may look something like this (JSON format):

{"Result":"Ok","Number":1234,"Time":"0:01","Entrants":9,"LateRegs":0,"Playing":9,"Removed":0,"Rebuys":0,"AddOns":0,"Smallest":1400,"Average":1500,"Largest":1600,"Prizepool":13500,"Payouts":3,"Payout":[6750,4050,2700]}

or in legacy format:

Result=Ok
Number=1234
Time=0:01
Entrants=9
LateRegs=0
Playing=9
Removed=0
Rebuys=0
AddOns=0
Smallest=1400
Average=1500
Largest=1600
Prizepool=13500
Payouts=3
Payout1=6750
Payout2=4050
Payout3=2700

TournamentsUnregister - removes a player specified by the Player parameter from the waiting list of a tournament specified by the Name parameter and refunds their account with the applicable buy-in.

TournamentsWaiting - retrieves the list of registered players in the waiting list for the tournament specified by the Name parameter. A sample response will look something like this (JSON format):

{"Result":"Ok","Count":3,"Wait":["Aces123","BoneCrusher","Wizard"]}

or in legacy format:

Result=Ok
Count=3
Wait1=Aces123
Wait2=BoneCrusher
Wait3=Wizard

Help Index | Home Page