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. 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.
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
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);
$response = trim(curl_exec($curl));
curl_close($curl);
$api = Array();
if ($assoc) // associative array result
{
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 (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.
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).
Although not technically part of the API, the server provides access to the communal avatar set and individual 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 <img> links on a web page. Use an Index parameter to retrieve an avatar from the communal set (default or custom) by its index number (starting with 1) or use a Player parameter to retrieve an avatar for a specific player. Examples:
http://12.34.56.789:8087/avatar?Index=10 http://12.34.56.789:8087/avatar?Player=Aces123
As documented below, there are over 50 API commands available in 7 categories:
Accounts - AccountsAdd, AccountsDecBalance, AccountsDelete, AccountsEdit, AccountsGet, AccountsIncBalance, AccountsList, AccountsSessionKey
Blacklist - BlacklistAdd, BlacklistDelete, BlacklistEdit, BlacklistGet, BlacklistList
Connections - ConnectionsGet, ConnectionsList, ConnectionsMessage, ConnectionsTerminate
Logs - LogsAddEvent, LogsError, LogsEvent, LogsHandHistory, LogsLobbyChat
Ring Games - RingGamesAdd, RingGamesDelete, RingGamesEdit, RingGamesGet, RingGamesList, RingGamesMessage, RingGamesOffline, RingGamesOnline, RingGamesPause, RingGamesPlaying, RingGamesResume, RingGamesWaiting
System - SystemGet, SystemSet, SystemEntryFeeDec, SystemEntryFeeGet, SystemEntryFeeInc, SystemEntryFeeSet, SystemRakeDec, SystemRakeGet, SystemRakeInc, SystemRakeSet, SystemReboot, SystemStats
Tournaments - TournamentsAdd, TournamentsDelete, TournamentsEdit, TournamentsGet, TournamentsList, TournamentsMessage, TournamentsOffline, TournamentsOnline, TournamentsPause, TournamentsPlaying, TournamentsRegister, TournamentsRemoveNoShows, TournamentsResults, TournamentsResume, TournamentsStart, TournamentsUnregister, TournamentsWaiting
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. A typical response will look something like this:
Result=Ok Player=Aces123 Title= Level= RealName=John T. PW=banana123 Location=Texas Email=aces123@gmail.com ValCode= Balance=5000 RingChips=1234 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 Chat=0000-00-00 00:00 ChatColor1= ChatColor2= Custom= Note= 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 all player accounts. Calling this with no parameters will just return the number of accounts. 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:
Player, Title, Level, RealName, PW, Location, Email, ValCode, Balance, RingChips, LastReset, Avatar, AvatarFile, Logins, FirstLogin, LastLogin, Gender, Chat, ChatColor1, ChatColor2, Custom, Note
A sample response with "Fields=Player,Balance" may look something like this:
Result=Ok Accounts=3 Player1=Aces123 Balance1=2345 Player2=BoneCusher Balance2=3470 Player3=David Balance3=1000
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/Misc topic for instructions on using session keys. A typical response will look something like this:
Result=Ok Player=Aces123 SessionKey=1234567890ABCDEF1234
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:
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:
Result=Ok Count=2 ID1=00000001 Player1=DeathBot IP1=12.34.56.789 ID2=00000002 Player2=TroubleMaker IP2=98.76.54.321
ConnectionsGet - retrieves values for the connection specified by the SessionID parameter. A typical response will look something like this:
Result=Ok SessionID=00000001 Status=Ok Player=Aces123 PC=12345678 IP=12.34.56.789 Connect=2008-07-22 14:07:23 Login=2008-07-22 14:24:56 LastAction=2008-07-22 14:52:01
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, Connect, Login, LastAction
A sample response with "Fields=Player,IP" may look something like this:
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.
ConnectionsTerminate - terminates the connection at the specified SessionID parameter.
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.
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:
Result=Ok Files=3 Date1=2009-03-01 Date2=2009-03-05 Date3=2009-03-06
Call with a Date parameter in the format of yyyy-mm-dd to retrieve the contents of an error log file. Example output will look something like this:
Result=Ok 2009-03-06 13:21:42|Remote admin whitelist denial for 127.0.0.1 2009-03-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:
Result=Ok Files=3 Date1=2009-03-01 Date2=2009-03-05 Date3=2009-03-06
Call with a Date parameter in the format of yyyy-mm-dd to retrieve the contents of an event log file. Example output will look something like this:
Result=Ok 2009-02-10 18:36:55|System|Game server started 2009-02-10 18:36:55|Table|Ring Game #1 opened 2009-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:
Result=Ok Files=2 Date1=2009-03-01 Name1=Ring Game #1 Date2=2009-03-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. Example output will look something like this:
Result=Ok Hand #3859-1 - 2009-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)
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:
Result=Ok Files=3 Date1=2009-03-01 Date2=2009-03-05 Date3=2009-03-06
Call with a Date parameter in the format of yyyy-mm-dd to retrieve the contents of a lobby chat log file. Example output will look something like this:
Result=Ok 2009-02-10 18:35:55 Alice: are you going to play in the tournament? 2009-02-10 18:36:14 Bob: yeah, see you there
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:
Result=Ok Name=Ring Game #1 Status=Playing: 9 Game=No Limit Hold'em PW= Private=No ObserverChat=Yes Seats=9 BuyInMin=500 BuyInMax=2500 BuyInDef=1500 Rake=0 RakeEvery=0 RakeMax=0 TurnClock=30 TimeBank=60 SmallBlind=10 BigBlind=20 Description= Auto=Yes
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, Game, PW, Private, ObserverChat, Seats, BuyInMin, BuyInMax, BuyInDef, Rake, RakeEvery, RakeMax, TurnClock, TimeBank, SmallBlind, BigBlind, Description, Auto
A sample response with "Fields=Name,Game" may look something like this:
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.
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.
RingGamesPause - pauses an online ring game specified by the Name parameter.
RingGamesPlaying - retrieves the list of seated players for the ring game specified by the Name parameter. A sample response may look something like this:
Result=Ok Player1=Aces123 Chips1=430 Net1=-70 Player2=BoneCrusher Chips2=650 Net2=150 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:
Result=Ok Count=3 Wait1=Aces123 Wait2=BoneCrusher Wait3=Wizard
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:
Result=Ok Value=8087
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.
SystemEntryFeeDec - decrements the balance for the Tournament Entry Fee Account by the number of chips specified in the Amount parameter. A "Balance" parameter will be returned in the result indicating the new balance for the account.
SystemEntryFeeGet - A "Balance" parameter will be returned in the result indicating the current balance for the account.
SystemEntryFeeInc - increments the balance for the Tournament Entry Fee Account by the number of chips specified in the Amount parameter. A "Balance" parameter will be returned in the result indicating the new balance for the account.
SystemEntryFeeSet - sets the balance for the Tournament Entry Fee Account to the number of chips specified in the Amount parameter.
SystemRakeDec - decrements the balance for the Ring Game Rake Account by the number of chips specified in the Amount parameter. A "Balance" parameter will be returned in the result indicating the new balance for the account.
SystemRakeGet - A "Balance" parameter will be returned in the result indicating the current balance for the account.
SystemRakeInc - increments the balance for the Ring Game Rake Account by the number of chips specified in the Amount parameter. A "Balance" parameter will be returned in the result indicating the new balance for the account.
SystemRakeSet - sets the balance for the Ring Game Rake Account to the number of chips specified in the Amount parameter.
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:
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:
Result=Ok Name=Tournament #1 Status=Playing: 6 of 9 Game=No Limit Hold'em PW= Private=No ObserverChat=Yes Tables=1 Seats=9 StartFull=Yes StartMin=1 StartCode=0 StartTime=0000-00-00 00:00 RecurMinutes=0 RemoveNoShows=No BuyIn=1500 EntryFee=0 PrizeBonus=0 MultiplyBonus=No Chips=1500 TurnClock=30 TimeBank=60 Level=10 RebuyLevels=0 BreakTime=0 BreakLevels=0 Description= 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 Auto=Yes
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, Game, PW, Private, ObserverChat, Tables, Seats, StartFull, StartMin, StartCode, StartTime, RecurMinutes, RemoveNoShows, BuyIn, EntryFee, PrizeBonus, MultiplyBonus, Chips, TurnClock, TimeBank, Level, RebuyLevels, BreakTime, BreakLevels, Description, Blinds, Auto
A sample response with "Fields=Name,Game" may look something like this:
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.
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.
TournamentsPause - pauses a running tournament specified by the Name parameter.
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. A sample response may look something like this:
Result=Ok Number=123456 Time=0:32 Player1=Aces123 Table1=1 Chips1=1650 Rank1=1 Player2=BoneCrusher Table2=1 Chips2=1475 Rank2=2 Player3=Dave Chips3=Finished Rank3=3 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.
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:
Result=Ok Files=2 Date1=2009-03-01 Name1=Tournament #2 Date2=2009-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:
Results=Ok Tournament=Tournament #1 Number=39 BuyIn=1500 PrizeBonus=0 Entrants=2 Start=2008-07-12 13:41:21 Place2=BoneCrusher (0) Place1=Aces123 (3000) Stop=2008-07-12 13:42:04 Tournament=Tournament #1 Number=40 BuyIn=1500 PrizeBonus=0 Entrants=3 Start=2008-07-12 17:11:26 Place3=DeathBot (0) Place2=Aces123 (0) Place1=BoneCrusher (4500) Stop=2008-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.
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:
Result=Ok Count=3 Wait1=Aces123 Wait2=BoneCrusher Wait3=WizardHelp Index | Home Page