# Sharkscope API Documentation **Version:** 1.0.113 **Date:** September 14, 2026 --- ## Quick Reference - **Base URL:** `https://www.sharkscope.com/api/{appname}/` - **Authentication:** MD5-hashed password + application key - **Response Formats:** XML, JSON (via Accept header) - **Timestamps:** Unix time (seconds since epoch) --- ## Table of Contents 1. [Request Format](#1-request-format) - [URL Format](#11-url-format) - [Authentication Parameters](#12-authentication-parameters) - [Headers](#13-headers) - [Password Encoding](#14-password-encoding) 2. [Response Format](#2-response-format) - [Basic Response Objects](#21-basic-response-objects) 3. [Resources](#3-resources) - [Generic Resources](#31-generic-resources) - [Sharkscope Client Resources](#32-sharkscope-client-resources) - [Player Resources](#33-player-resources) - [PlayerGroup Maintenance](#34-playergroup-maintenance-resources) - [Tournament Resources](#35-tournament-resources) - [Active Tournaments](#36-active-tournaments) - [Leaderboard Resources](#37-leaderboard-resources) - [Network Resources](#38-network-resources) - [User Resources](#39-user-resources) - [Report Resources](#310-report-resources) - [Filter Documentation](#311-filter) - [Natural Language Query](#312-natural-language-query) - [Missing Games](#313-missing-games-resources) - [Missing Games by IDs](#3131-missing-games-by-ids) - [Missing Games by Summary](#3132-missing-games-by-summary) - [List PokerCraft Permitted Viewers](#3133-list-pokercraft-permitted-viewers) - [Add PokerCraft Permitted Viewer](#3134-add-pokercraft-permitted-viewer) - [Remove PokerCraft Permitted Viewer](#3135-remove-pokercraft-permitted-viewer) - [Upload PokerCraft Data](#3136-upload-pokercraft-data) - [Request PokerCraft Name Transfer](#3137-request-pokercraft-name-transfer) - [List Uploaded PokerCraft Data](#3138-list-uploaded-pokercraft-data) - [List PokerCraft Players](#3139-list-pokercraft-players) - [Update PokerCraft Player Privacy](#31310-update-pokercraft-player-privacy) - [Delete Specific PokerCraft Upload](#31311-delete-specific-pokercraft-upload) - [Delete PokerCraft Player Uploads](#31312-delete-pokercraft-player-uploads) - [Deal Resources](#314-deal-resources) - [Private Leaderboards](#315-private-leaderboard-resources) - [Stable Resources](#316-stable-resources) - [Tracking Outages](#317-tracking-outage-resources) - [Tournament Calendar](#318-tournament-calendar-resources) 4. [Response Objects](#4-response-objects) 5. [Errors](#5-errors) --- ## Revision History | Version | Date | Changes | |---------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | | 1.0.113 | 14 Sep 2026 | Tournament by ID (section 3.5.1): completed tournaments can now order their player entries by prize, with the `order` values `Prize` (bounties included), `BountyPrize` and `PrizeExcludingBounty`. Entries without the figure come last in either direction. | | 1.0.112 | 6 Sep 2026 | Documented the Tournament Player Edges resource (`/networks/{network}/tournaments/{id}/edges`, section 3.5.11): each named player's expected return if they entered a registering tournament, from their own record, for up to 20 players per request. One search, spent only when at least one player had a profile to answer from; players without one are queued and answered on a later request. | | 1.0.111 | 26 Aug 2026 | Documented the Reported Rebuys resource (`POST`/`DELETE` `/networks/{network}/players/{name}/tournaments/{id}/rebuys`) for reporting rebuys and re-entries on your own player names, and noted the `individualRebuysUnknown` attribute that marks which tournaments accept one. Brought the rest of the spec back in line with the API: added Countries, Hand Analysis, Player Tags, Group Note, Group Tags, Subgroups, Group Alerts, the reseller sale preview/edit/remove resources, and a new Tournament Calendar section covering labels, their members, rules and alerts. Corrected the Version Check path to `/client/{downloadType}/version`. Completed the 200xxx error code reference, which stopped at 200081. Restored the 3.11 Filter section holding the `Type` code table, and removed a duplicated copy of 3.12 Natural Language Query. Withdrew the player report resources and the label calendar (ICS) feed from the public API - they remain available to signed-in callers but are no longer published. Removed 25 error codes that only SharkScope's own tooling can produce (background tasks, database servers and processes, admin player locks, checkout, embedded widgets, collusion reports and alert publishing). | | 1.0.110 | 6 Jun 2026 | Documented relative `Date` filter ranges for Active Tournaments (offset units `Y/M/W/D/H/S`, the negative-offset "future" form `Date:-1D`, and inverted `!` windows). **Behaviour change:** the per-player `activeTournaments` endpoint now applies inverted `Date`/`EndDate` exactly like the network endpoint (`start <= now + offset`); previously its inverted sign was reversed (`Date!:-600S`). Corrected the `activeTournaments.csv` example to `Date!:600S`. | | 1.0.109 | 6 May 2026 | Documented the network-scoped Active Tournaments JSON/XML resource (`/api/{appname}/networks/{network}/activeTournaments`) as section 3.5.10. | | 1.0.108 | 19 Apr 2026 | Documented the `OverrideReEntries` filter constraint for NLQ and clarified its difference from the existing `ReEntries` filter. | | 1.0.107 | 2 Apr 2026 | Added `D1` (Day 1) and `FD` (Final Day) tournament Type flags to the filter documentation. Added the `multiday` tournament response attribute. | | 1.0.106 | 29 Mar 2026 | Documented the `timezone` query parameter for both CSV exports: player tournament export (`/tournaments.csv`) and active tournaments export (`/activeTournaments.csv`), including their `America/Los_Angeles` default and IANA timezone handling | | 1.0.105 | 9 Mar 2026 | Documented `Subscriptions` / `Subscription` quota-period fields in `UserInfo`, including `quotaPeriod`, `searchesPerQuotaPeriod`, `nextQuotaResetDate`, `totalSearchesRemaining`, and `freeSearchesRemaining` | | 1.0.104 | 8 Feb 2026 | Added new Limit/Order options of BiggestPrizepool, SmallestPrizepool, GreatestBuyin and LeastBuyin | | 1.0.103 | 4 Feb 2026 | Added Player tournaments CSV export resource (`/tournaments.csv`) | | 1.0.102 | 6 Jan 2026 | Changed Spec document foramt to .md from .doc | | 1.0.101 | 6 Jan 2026 | Added comprehensive PokerCraft resources (Upload, List, Delete, Player Privacy, Name Transfer) | | 1.0.100 | 10 Dec 2025 | Minor clarifications | | 1.0.99 | 7 Mar 2025 | Removed SharkScope Push service as an option | | 1.0.98 | 1 Feb 2025 | Added option to exclude Not opted in players and opted out players from Player Group search results | | 1.0.97 | 21 Dec 2024 | Added Natural Language Query, plus additional filter constraints Position and HourOfDay, and new Limit constraint order options of Largest, Smallest, HighestROI and LowestROI | | 1.0.96 | 7 Aug 2024 | Added Tracking Outage notification resources | | 1.0.95 | 4 Apr 2024 | Added EndDate filter and clarified that the existing Date filter now uses the start date of the tournament | | 1.0.94 | 9 Jan 2024 | Added ability to assign and managed Permitted Viewers of uploaded PokerCraft data | | 1.0.93 | 14 Dec 2023 | Clarified Player Group creation and removed legacy references to Vs Player flag | | 1.0.92 | 30 Nov 2023 | **BREAKING CHANGE:** The /playergroups request is now deprecated and is scheduled for removal in an upcoming release. It has been superseded by the /playergroups/list request, offering enhanced performance. This new request omits member details; these must now be obtained individually for each group | | 1.0.91 | 6 Nov 2023 | Reduced the cost of Completed Tournaments for Players request for GG networks to allow the request to go up to 21 days for those networks | | 1.0.90 | 1 Nov 2023 | Added privacy option to PokerCraft resource | | 1.0.89 | 26 Oct 2023 | Added Direct Results Upload from PokerCraft resource | | 1.0.88 | 29 Aug 2023 | Clarified some details about the DailyScheduled Reports | | 1.0.87 | 14 Aug 2023 | Updated Error Codes and Tournament Flags | | 1.0.86 | 5 Jul 2023 | Enabled completedTournament resource for set of players to work with any date range | | 1.0.85 | 15 Apr 2023 | Reduced cost of completedTournament resource for set of players | | 1.0.84 | 23 Aug 2022 | Added completedTournament resource for set of players | | 1.0.83 | 9 Mar 2022 | Corrected Deal Activation example code | | 1.0.82 | 13 Jan 2022 | Added paging option to tournament by Id resource | | 1.0.81 | 16 Dec 2021 | Added tournaments resource | | 1.0.80 | 21 Nov 2021 | Added User Usage History | | 1.0.79 | 15 Nov 2021 | Added Player Insights. Fixed typo in MarketShare resource URL | | 1.0.78 | 1 May 2021 | Fixed typo in Graph type | | 1.0.77 | 2 Feb 2021 | Fixed typo in Ordering param | | 1.0.76 | 24 Dec 2020 | Added Next/Previous Tournament resources | | 1.0.75 | 10 Dec 2020 | Daily Scheduled Reports now available for all Commercial Gold subscribers and include AvAbility by default | | 1.0.74 | 12 May 2020 | Added noPlayers option to Tournament resource | | 1.0.73 | 22 Apr 2020 | Removed Player Leaderboard Ranks resource as it duplicates functionality in the Player Profile resource | | 1.0.72 | 4 Mar 2020 | Added expandMultiEntries option to Tournament resource | | 1.0.71 | 21 Feb 2020 | Added Private Leaderboard Edit Functionality | --- ## 1. Request Format ### 1.1 URL Format ``` https://www.sharkscope.com/api/{appname}/{resource_path}?{parameters} ``` | Component | Description | |-----------|-------------| | `appname` | Your application name (allocated by SharkScope) | | `resource_path` | Path to specific resource | | `parameters` | Request parameters (auth, filter, etc.) | ### 1.2 Authentication Parameters Include username (cleartext) and password (MD5 hex): ``` ?Username=someone@somewhere.com&Password=ea3df3c7fa3557d23d2cf889b1a4c90d ``` ### 1.3 Headers | Header | Required | Value | |--------|----------|-------| | `Accept` | Yes | `application/xml` or `application/json` | | `Username` | Optional* | Email address | | `Password` | Optional* | MD5 hashed password | | `User-Agent` | Yes | Non-empty string (e.g., "Mozilla") | *Username/Password can be headers OR parameters ### 1.4 Password Encoding **Two-step process:** 1. MD5 hash the password 2. MD5 hash (result + application_key) **Java Example:** ```java String encodedPassword = "ea3df3c7fa3557d23d2cf889b1a4c90d"; String applicationKey = "21f5e7aa7893caf0"; String key = encodedPassword.toLowerCase() + applicationKey; MessageDigest algorithm = MessageDigest.getInstance("MD5"); algorithm.update(key.getBytes()); byte[] digest = algorithm.digest(); StringBuffer hexString = new StringBuffer(); for (int i = 0; i < digest.length; i++) { int val = 0xFF & digest[i]; if (val < 16) hexString.append('0'); hexString.append(Integer.toHexString(val)); } return hexString.toString().toLowerCase(); ``` **Ruby Example:** ```ruby require 'digest/MD5' def encode(encoded_password, application_key) key = encoded_password.downcase + application_key Digest::MD5.hexdigest(key) end ``` **C++ Example:** ```cpp #include char encodedPassword[] = "ea3df3c7fa3557d23d2cf889b1a4c90d"; char applicationKey[] = "21f5e7aa7893caf0"; char combined[49]; strcpy(combined, encodedPassword); strcat(combined, applicationKey); unsigned char digest[MD5_DIGEST_LENGTH]; MD5((unsigned char*)combined, strlen(combined), digest); char result[(MD5_DIGEST_LENGTH * 2) + 1]; for (int i = 0; i < MD5_DIGEST_LENGTH; i++) sprintf(result + (i * 2), "%02x", digest[i]); ``` --- ## 2. Response Format ### Status Codes - `200 OK` - Successful request - `404 Not Found` - Invalid endpoint - `405 Method Not Allowed` - Wrong HTTP method ### 2.1 Basic Response Objects #### 2.1.1 Response Root ```xml ... ``` **Attributes:** - `success`: `true` or `false` - `timestamp`: Unix timestamp (seconds since epoch) - `metadataHash`: Latest metadata version - `appVersion`: Application version number #### 2.1.2 UserInfo ```xml someone@somewhere.com 56 1523644928 en-gb,en;q=0.7,el;q=0.3 ``` For unauthenticated users: ```xml 5 en-gb,en;q=0.7,el;q=0.3 ``` For authenticated users with active subscriptions, `UserInfo` may also include a `Subscriptions` element: ```xml someone@somewhere.com 56 1523644928 1523644928 ``` **`Subscriptions` attributes:** - `totalSearchesRemaining`: Combined remaining searches currently available to the user. - `freeSearchesRemaining`: Remaining searches coming from free search providers. **`Subscription` quota-related attributes:** - `class`: Subscription role class name. - `quotaPeriod`: Search quota renewal period. Possible values: `LIFETIME`, `DAILY`, `MONTHLY`. - `searchesPerQuotaPeriod`: Search quota attached to the subscription class for each quota period. - `nextQuotaResetDate`: Unix timestamp for the next time the quota period resets. - `DAILY`: The next midnight Pacific time. - `MONTHLY`: The next upcoming monthly anniversary calculated in whole months from the payment date/start date. - `LIFETIME`: Omitted or `null`. **Other `Subscription` attributes commonly returned alongside quota fields:** - `accessLevel`: Access level granted by the subscription class. - `commercial`: Present and `true` for commercial/pro role classes. - `expirationDate`: Unix timestamp when the subscription expires. - `renewalDate`: Unix timestamp for the next recurring renewal date, when applicable. - `recurring`: Present and `true` if the subscription is recurring and not cancelled. - `subID`: Provider subscription identifier for recurring subscriptions. - `primary`: Present and `true` for the primary subscription in the list. - `assignedBy`: Username of the assigning user for shared subscriptions. #### 2.1.3 ErrorResponse ```xml Invalid password. ``` --- ## 3. Resources ### 3.1 Generic Resources #### 3.1.1 Metadata Get API metadata including filters, networks, currencies, and statistics definitions. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | No | | **Cost** | Free | | **Path** | `/metadata` | | **Parameters** | `hash` (optional) | **Example:** ``` GET /api/someapp/metadata?hash=f23ffdbb97027412c39cdba36e28b363 ``` **Response:** `MetadataResponse` (cached if hash matches) #### 3.1.2 What's New Get public SharkScope What's New items, localized to the caller's preferred language. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | No | | **Cost** | Free | | **Path** | `/news/whatsnew` | | **Parameters** | `limit` (optional, `0` = all items) | **Example:** ``` GET /api/someapp/news/whatsnew?limit=10 ``` **Response:** `WhatsNewResponse` Each `WhatsNewItem` may include: - `id` - `Date` - `Title` - `Category` - `Content` - `ImageUrl` - `YouTubeUrl` - `Link` Only enabled/published items are returned. #### 3.1.3 Countries Get the countries SharkScope recognises, for country pickers and country-based filters. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | No | | **Cost** | Free | | **Path** | `/metadata/countries` | **Example:** ``` GET /api/someapp/metadata/countries ``` #### 3.1.4 Hand Analysis Submit one hand history for AI-assisted analysis and receive a natural-language assessment of how the hand was played. | Property | Value | |----------|-------| | **Method** | POST | | **Auth** | Required (Subscriber) | | **Cost** | 5 searches | | **Path** | `/handanalysis` | | **Parameters** | `langCode` (optional, default `en`) | **Notes:** - The hand history is the request body, as plain text. - `langCode` selects the language of the analysis, not of the hand history. **Example:** ``` POST /api/someapp/handanalysis?langCode=de PokerStars Hand #123456789: Tournament #987654321, $10+$1 USD Hold em No Limit ... ``` --- ### 3.2 Sharkscope Client Resources #### 3.2.1 Download Resource Redirect to download installer or updater. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | No | | **Cost** | Free | | **Path** | `/client/[installer\|updater]` | **Example:** ``` GET /api/someapp/client/installer ``` #### 3.2.2 Version Check Get latest client version number. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | No | | **Cost** | Free | | **Path** | `/client/{downloadType}/version` | | **Parameters** | `version` (optional, the version the client is currently running) | **Example:** ``` GET /api/someapp/client/installer/version?version=3 ``` **Response:** `VersionCheckResponse` --- ### 3.3 Player Resources **Base Path:** `/api/{appname}/networks/{network}/players/{playername}/` #### Network Specifiers Request multiple networks using specifiers: | Specifier | Description | Example | |-----------|-------------|---------| | `all~net1,net2` | Search all specified networks | `all~fulltilt,pokerstars` | | `any~net1,net2` | Search until player found | `any~fulltilt,pokerstars` | | `*~net1,net2` | Alias for `all~` | `*~fulltilt,pokerstars` | | `@~net1,net2` | Alias for `any~` | `@~fulltilt,pokerstars` | | `net1,net2` | Implied `any` | `fulltilt,pokerstars` | **Note:** Tilde (~) is used as the delimiter because colon (:) is technically not permitted URL paths. **Special:** `allpokerstars` = `all~pokerstars,pokerstarsit,pokerstarsfr,pokerstarses` (expanded to comma-separated list) **Note:** Player names must be URL encoded (UTF-8) #### 3.3.1 Summary Get player summary with stats and recent tournaments. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 search | | **Path** | Root (network specifier supported) | | **Parameters** | `filter`, `mode`, `lastUpdateTime`, `groupsExcludeOptedOut`, `groupsExcludeNotOptedIn` | **Mode options:** - `normal` (default) - `vsuseronblocked` - Only tournaments vs user (if user blocked) - `vsuser` - Both all tournaments and vs-user stats **Example:** ``` GET /api/someapp/networks/fulltilt/players/tom GET /api/someapp/networks/*~fulltilt,pokerstars/players/tom?mode=vsuser ``` #### 3.3.2 Completed Tournaments Get recent completed tournaments. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 1 search per 100 tournaments | | **Path** | `/completedTournaments` | | **Parameters** | `order`, `filter`, `lastUpdateTime` | **Order formats:** - `Best,1~50` - Best 50 tournaments - `Worst,1~100` - Worst 100 tournaments - `First,1~20` - First 20 chronologically - `Last,1~10` - Last 10 chronologically - `BiggestPrizepool,1~10` - Biggest prize pool tournaments - `SmallestPrizepool,1~10` - Smallest prize pool tournaments - `GreatestBuyin,1~10` - Highest buy-in tournaments - `LeastBuyin,1~10` - Lowest buy-in tournaments - `player,1~1000` - For groups, by player **Example:** ``` GET /api/someapp/networks/fulltilt/players/tom/completedTournaments?order=Best,1~50 ``` **Notes:** - A tournament carrying `individualRebuysUnknown="true"` is one the network publishes no per-player rebuy/re-entry count for, so the figure shown is spread from the tournament total. For your own player names you can replace it with the real count - see [Reported Rebuys](#3317-reported-rebuys). #### 3.3.3 Active Tournaments Get currently running/registering tournaments. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 search | | **Path** | `/activeTournaments` | | **Parameters** | `order`, `filter`, `groupsExcludeOptedOut`, `groupsExcludeNotOptedIn` | **Tip - relative `Date` ranges:** A relative `Date` value is an offset from now (units `Y`/`M`/`W`/`D`/`H`/`S`; the integer may be negative). A plain constraint keeps `start >= now - offset`, so a *negative* offset reaches into the future (e.g. `Date:-1D` = starting more than 24 h out). Invert with `!` to bound the upper end (`start <= now + offset`), pairing it with `Date:0S` for a window: ``` filter=Date:0S;Date!:600S // tournaments starting in the next 10 minutes ``` This endpoint applies the same `Date`/`EndDate` semantics as the network endpoint - see **Relative `Date` ranges** in section 3.5.10 for the full reference. #### 3.3.4 Statistics Get detailed statistics (no tournaments). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | Varies by statistic type | | **Path** | `/statistics` or `/statistics/{stat1},{stat2}` | | **Parameters** | `filter`, `lastUpdateTime` | **Examples:** ``` GET /api/someapp/networks/fulltilt/players/tom/statistics GET /api/someapp/networks/fulltilt/players/tom/statistics/TotalStake,TotalCashes,Streaks ``` #### 3.3.5 Suggestions Get player name suggestions (autocomplete). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | Varies | | **Path** | `/suggestions` | | **Parameters** | `limit` (default: 25) | #### 3.3.6 User Note Get/set/delete notes on a player. | Property | Value | |----------|-------| | **Method** | GET/POST/DELETE | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | `/usernote` | | **Parameters** | `notes` (for POST) | #### 3.3.7 OptOut Request player opt-out. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Optional | | **Cost** | 0 | | **Path** | `/optout` | | **Parameters** | `email` (optional) | **Example:** ``` GET /api/someapp/networks/fulltilt/players/tom/optout ``` #### 3.3.8 OptIn Request player opt-in and remove existing resets/opt-outs. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/optin` | | **Parameters** | `email` (optional) | **Example:** ``` GET /api/someapp/networks/fulltilt/players/tom/optin ``` #### 3.3.9 Confirm Opt Change Confirm opt in/out change via email ID. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | No | | **Cost** | 0 | | **Path** | `/confirmoptchange` | | **Parameters** | `id` | **Example:** ``` GET /api/someapp/networks/fulltilt/players/tom/confirmoptchange?id=ABC123 ``` #### 3.3.10 Reset Reset player stats from a specific date. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | `/reset` | | **Parameters** | `StartDateTime` (optional) | **Example:** ``` GET /api/someapp/networks/fulltilt/players/tom/reset ``` #### 3.3.11 Graph Get player avatar/graph in SVG format. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 search | | **Path** | `/graph` | | **Parameters** | `type`, `filter`, `freshness`, `width`, `height` | **Graph Types:** | Type | Description | Size (W×H) | |------|-------------|------------| | `MiniSummary` | Stats plaque with leaderboard icon | 130×65 | | `ProfitHistory` | Small profit graph | 250×250 | | `ProfitHistoryLarge` | Large profit graph with stats | 600×250 | | `ByStake` | ROI and games by stake | 250×250 | | `ByEntrants` | ROI and profit by game size | 250×250 | **Freshness:** Interval in seconds (default: 10800 = 3 hours) #### 3.3.12 Profile Get last activity timestamp. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/profile` | #### 3.3.13 Timeline Get player's timeline with all events. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/timeline` | #### 3.3.14 Timeline Event Get specific timeline event by ID. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/timeline/{id}` | #### 3.3.15 Insights Get performance predictions and recommendations. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 1 (0 if searched <1 min ago) | | **Path** | `/insights` | | **Parameters** | `currency` (default: USD), `timezoneOffset` (default: 7) | #### 3.3.16 Tournaments CSV Export Download recent completed tournaments as a CSV file. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 25 credits per 5 unique players included (minimum 25 credits). | | **Path** | `/tournaments.csv` | | **Parameters** | `filter`, `expandMultiEntries`, `timezone` | **Notes:** - Returns a downloadable attachment named `tournaments.csv`. - Response content type is CSV (`application/csv`). - `timezone` accepts an IANA timezone ID such as `Europe/London` or `America/New_York`. - If `timezone` is omitted, date/time columns in the export default to `America/Los_Angeles`. **Parameters:** - `filter` - Optional tournament filter string. - `expandMultiEntries` - `true` to split multi-entry/rebuy results into separate rows (default: `false`). - `timezone` - Optional IANA timezone ID used to render the CSV date/time columns. **Example:** ``` GET /api/someapp/networks/pokerstars/players/someplayer/tournaments.csv?filter=Date:30D¤cy=USD&expandMultiEntries=true&timezone=Europe/London ``` #### 3.3.17 Reported Rebuys Report how many extra entries you bought in a tournament - rebuys on a rebuy tournament, re-entries on a re-entry tournament - for one of your own player names. | Property | Value | |----------|-------| | **Method** | POST/DELETE | | **Auth** | Required (the player must be one of your personal player names) | | **Cost** | 0 | | **Path** | `/tournaments/{id}/rebuys` | | **Parameters** | `count` (POST only, 0-50) | **Notes:** - `count` counts the entries beyond the first: a player who entered once and never re-entered is `0`, one who fired three bullets is `2`. - Only tournaments SharkScope receives no per-player count for accept a report. Those carry `individualRebuysUnknown="true"` in the Completed Tournaments response; any other tournament is refused (200087), because the count held there came from the poker network and is not an estimate. - Where no count has been reported, a tournament's total rebuys are shared evenly across its entrants. A report replaces that estimate with what actually happened for that player, and their statistics are recalculated from it. - The player must be one of your personal player names (200107 otherwise). A rebuy count changes that player's investment, and so their profit and ROI, so it is only taken from the person who played. - `DELETE` withdraws a count reported earlier and puts the player back on the tournament average. Withdrawing a count that was never reported succeeds and changes nothing. - Counts SharkScope recorded itself cannot be overwritten or withdrawn (200088). - Sending a count that matches the one already stored succeeds and returns `inserted="0"`. **Examples:** ``` POST /api/someapp/networks/wptglobal/players/tom/tournaments/649097/rebuys?count=2 DELETE /api/someapp/networks/wptglobal/players/tom/tournaments/649097/rebuys ``` **Response:** `RebuyResponse` ```xml ``` `inserted` is the number of stored rows the call changed; `rebuys` is the count now held, and is omitted after a `DELETE`. #### 3.3.18 Player Tags Add or remove a tag on a player. Tags are free-text labels, private to you, for organising the players you follow. | Property | Value | |----------|-------| | **Method** | POST/DELETE | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | `/tags/{tag}` | **Notes:** - A player may carry up to 12 tags. A tag may be up to 30 characters, may not be blank, and may not contain a slash. - Tags are matched case-insensitively, so a tag differing only in capitalisation is the same tag. - Both calls are idempotent: adding a tag the player already carries, or removing one they do not, succeeds and changes nothing. A client can send its whole set without working out the difference first. - Tags cannot be set on the `PlayerGroup` pseudo-network - see [Group Tags](#3411-group-tags). - There is no per-player GET. Read every tag you hold in one request with [User Notes (Bulk)](#3913-user-notes-bulk), passing `includeTags=true`. **Examples:** ``` POST /api/someapp/networks/fulltilt/players/tom/tags/regular DELETE /api/someapp/networks/fulltilt/players/tom/tags/regular ``` **Response:** `UserNotesResponse` carrying the player and its tags after the change. --- ### 3.4 PlayerGroup Maintenance Resources **Base Path:** `/api/{appname}/playergroups/{groupname}` **Special:** Use `personal` as groupname for your personal group #### 3.4.1 List List user's player groups (excludes personal group). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | `/list` | **Note:** Does NOT include member details (fetch individually) #### 3.4.2 Retrieval Get group info with members. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | Root | **Example:** ``` GET /api/someapp/playergroups/MyGroup GET /api/someapp/playergroups/personal ``` #### 3.4.3 Modification Modify group flags or name. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | `/modify` | | **Parameters** | `public` (y/n), `consolidated` (y/n), `name` | **Flags:** - **public**: Group appears in searches - **consolidated**: Group behaves as single player **Example:** ``` GET /api/someapp/playergroups/MyGroup/modify?public=y&consolidated=n ``` #### 3.4.4 Adding Players / Creating Groups Add member (creates group if first member). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/members/{network}/{playername}` | | **Parameters** | `blogicon`, `filter` | **Default:** Groups created as private and consolidated **Example:** ``` GET /api/someapp/playergroups/MyGroup/members/fulltilt/tom GET /api/someapp/playergroups/personal/members/fulltilt/tom?blogicon=true&filter=Date:1Y ``` #### 3.4.5 Modifying Members Modify blog icon (personal groups only). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/members/{network}/{playername}/modify` | | **Parameters** | `blogicon` | #### 3.4.6 Deleting Members Remove player from group. | Property | Value | |----------|-------| | **Method** | DELETE | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | `/members/{network}/{playername}` | **Note:** Deleting last member deletes the group #### 3.4.7 Deleting Group Delete entire group. | Property | Value | |----------|-------| | **Method** | DELETE | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | Root | #### 3.4.8 Duplicating Group Duplicate a group into a new group (same members). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | `/duplicate` | | **Parameters** | `name` | **Notes:** - `groupname` cannot be `personal` - Caller must own the group - `name` must be unique **Example:** ``` GET /api/someapp/playergroups/MyGroup/duplicate?name=MyGroupCopy ``` #### 3.4.9 Moving Group Move a group to a different account (transfer ownership). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | `/move` | | **Parameters** | `email` | **Notes:** - `groupname` cannot be `personal` - Caller must own the group - `email` must match an existing account **Example:** ``` GET /api/someapp/playergroups/MyGroup/move?email=someone@somewhere.com ``` #### 3.4.10 Group Note Get, set or delete the note held against a player group. One note per group, private to you. | Property | Value | |----------|-------| | **Method** | GET/POST/DELETE | | **Auth** | Required (Subscriber) | | **Cost** | 0 | | **Path** | `/{groupname}/note` | | **Parameters** | `notes` (POST, form-encoded) | **Notes:** - You must own the group. - This is the note on the group itself. Notes on the players inside it are separate - see [User Note](#336-user-note). **Example:** ``` POST /api/someapp/playergroups/MyGroup/note Content-Type: application/x-www-form-urlencoded notes=Sunday%20crew ``` #### 3.4.11 Group Tags Add or remove a tag on a player group. | Property | Value | |----------|-------| | **Method** | GET (add) / DELETE (remove) | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/{groupname}/tags/{tag}` | **Notes:** - You must own the group. The personal group cannot be tagged and is reported as not found. - Both calls are idempotent: adding a tag the group already has, or removing one it does not carry, succeeds and changes nothing. **Examples:** ``` GET /api/someapp/playergroups/MyGroup/tags/regulars DELETE /api/someapp/playergroups/MyGroup/tags/regulars ``` **Response:** `PlayerGroupResponse` carrying the group's tags after the change. #### 3.4.12 Subgroups (Nested Groups) Link one group into another, or copy players between them. | Resource | Method | Description | |----------|--------|-------------| | `/{groupname}/subgroups/{subgroup}` | GET | Link `{subgroup}` into `{groupname}` | | `/{groupname}/subgroups/{subgroup}` | DELETE | Remove the link | | `/{groupname}/subgroups/{subgroup}/copymembers` | GET | Copy every player in `{subgroup}` into `{groupname}` | **Properties:** - Auth: Required (Subscriber; nesting is a Pro feature) - Cost: 0 **Notes:** - Linking stays live: the linked group's players count as members of the parent, and adding or removing players in the linked group is reflected in the parent straight away. Copying is one-time - the two groups are not linked afterwards, so later changes to the source do not appear in the target. - You must own both groups to link them. To copy, you must own the target; the source only has to be one you can read, so copying from a public group is allowed. - A group cannot link itself, cannot form a cycle, cannot nest more than five levels deep, and cannot take the parent past 2000 players once flattened. A private group cannot be linked into a public one. The personal group cannot be used on either side. - `memberCount` continues to report only the players stored directly against the parent; `effectiveMemberCount` reports the flattened total, and is what a search of the group is priced on. - Where a linked group has since been deleted its name can no longer be resolved, so its numeric id may be given instead when unlinking. **Examples:** ``` GET /api/someapp/playergroups/MyGroup/subgroups/SundayGrinders GET /api/someapp/playergroups/MyGroup/subgroups/SundayGrinders/copymembers DELETE /api/someapp/playergroups/MyGroup/subgroups/SundayGrinders ``` #### 3.4.13 Group Alerts Alert rules watch a group's members and deliver what fires to your connected destinations. | Resource | Method | Description | |----------|--------|-------------| | `/{groupname}/alerts` | GET | Rules on the group, plus the alerts they recently produced | | `/{groupname}/alerts/create` | GET | Create a rule | | `/{groupname}/alerts/{id}/update` | GET | Update a rule | | `/{groupname}/alerts/{id}/delete` | GET | Delete a rule | | `/{groupname}/alerts/{id}/test` | GET | Send a test alert through the rule's destinations | | `/{groupname}/alerts/acknowledge` | GET | Mark delivered alerts as read | **Properties:** - Auth: Required (Subscriber, Pro plan) - Cost: 0 - these read stored rules and a delivery log, and never touch tournament data **Parameters:** - `trigger` (create) - `cash`, `win`, `finaltable`, `stakeabove`, `stakebelow`, `format`, `leaderboard`, `newscreenname`, `registered`, `playingnow`, `gonequiet` - `ruleName` - optional label for the rule; defaults to the trigger's name - `scope` / `scopeValue` - `all` (default), `tag` or `member`, with `scopeValue` naming the tag or the member - `channels` / `digestChannels` - comma-separated destination ids, delivered as they fire or rolled into a digest. The in-app feed is always included whatever you send - `amount`, `currency`, `minEntrants`, `formats`, `days`, `topN` - trigger-specific thresholds - `enabled` (update) - `true` (default) or `false` - `ruleID` (acknowledge) - optional; acknowledges one rule instead of the whole group **Examples:** ``` GET /api/someapp/playergroups/MyGroup/alerts GET /api/someapp/playergroups/MyGroup/alerts/create?trigger=cash&amount=1000¤cy=USD&channels=12 GET /api/someapp/playergroups/MyGroup/alerts/17/delete GET /api/someapp/playergroups/MyGroup/alerts/acknowledge ``` **Response:** `PlayerGroupAlertsResponse` --- ### 3.5 Tournament Resources **Base Path:** `/api/{appname}/networks/{network}/tournaments` #### 3.5.1 Tournament by ID Get specific tournament details. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 (free for 3 hours) | | **Path** | `/{tournamentId}` | | **Parameters** | `lastUpdateTime`, `expandMultiEntries`, `noPlayers`, `order` | **Parameters:** - `expandMultiEntries=true` - Separate rows for multi-entry - `noPlayers=true` - Exclude player list - `order=Player,1~25,desc` - Paginate players (Player or Position) - `order=BountyPrize,1~25,desc` - Completed tournaments can also be ordered by `Prize` (the `prize` attribute, bounties included), `BountyPrize` (`prizeBountyComponent`) or `PrizeExcludingBounty` (the prize for the finishing position). Entries without that figure come last in either direction; equal figures are ordered by position. **Example:** ``` GET /api/someapp/networks/fulltilt/tournaments/123456789 ``` #### 3.5.2 Registering Tournaments Get registering tournaments. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 (free for 1 minute) | | **Path** | Root | | **Parameters** | `limit`, `filter` | #### 3.5.3 Tournaments Get completed tournaments (no player results, stats only). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 per 10 tournaments | | **Path** | `/tournaments` | | **Parameters** | `filter`, `order` (First/Last only) | **Limitation:** Max 1 month old **Example:** ``` GET /api/someapp/networks/fulltilt/tournaments?filter=Type:OMAHA&Order=Last,1~10 ``` #### 3.5.4 Completed Tournaments (Bulk Players) Get results for up to 2,000 players (any Pro / commercial subscription, Pro 5K+). | Property | Value | |----------|-----------------------------------------| | **Method** | POST | | **Auth** | Required (any Pro / commercial subscription, Pro 5K+) | | **Cost** | See below | | **Path** | `/completedTournaments` | | **Parameters** | `filter`, `players` (newline-delimited) | **Cost Structure:** - **No date filter:** 1 per player (max cost 10), last 4 days (21 days for GG) - **With date filter:** 1 per player (max cost 10) × days in range **Example:** ``` POST /api/someapp/networks/fulltilt/completedTournaments Content-Type: application/x-www-form-urlencoded players=player1%0Aplayer2%0Aplayer3 ``` #### 3.5.5 Bare Tournaments Get tournament info by IDs (no players). | Property | Value | |----------|-------| | **Method** | GET/POST | | **Auth** | Required | | **Cost** | 1 per 100 tournaments | | **Path** | `/bareTournaments` | | **Parameters** | `tournamentIDs` | **ID Formats:** ``` // Single network tournamentIDs=376797050,375781297 // Multiple networks tournamentIDs=pokerstars,1234,5678,fulltilt,9012 // Multi-line format pokerstars 1234 5678 fulltilt 9012 // PokerStars family tournamentIDs=allpokerstars,1234,5678 ``` **Example:** ``` GET /api/someapp/networks/fulltilt/bareTournaments?tournamentIDs=376797050,375781297 ``` #### 3.5.6 Running Chips Tournaments Get current chip counts (polling required). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 (when COMPLETED) | | **Path** | `/tournaments/{id}/chips` | **States:** - `SUBMITTED` - Request received/pending - `ERROR` - Unable to retrieve - `COMPLETED` - Data ready **Polling:** - Interval: ~10 seconds - Timeout: 2 minutes - Cache: 5 minutes **Response Example:** ```xml ``` #### 3.5.7 Next Tournament Get chronologically next completed tournament of same type. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 search | | **Path** | `/tournaments/{id}/next` | | **Parameters** | `expandMultiEntries`, `noPlayers` | **Example:** ``` GET /api/someapp/networks/fulltilt/tournaments/123456789/next ``` #### 3.5.8 Previous Tournament Get chronologically previous completed tournament of same type. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 search | | **Path** | `/tournaments/{id}/previous` | | **Parameters** | `expandMultiEntries`, `noPlayers` | **Example:** ``` GET /api/someapp/networks/fulltilt/tournaments/123456789/previous ``` #### 3.5.9 Active Tournaments CSV Export Download active tournaments as a CSV file. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 15 searches | | **Path** | `/activeTournaments.csv` | | **Parameters** | `filter`, `limit`, `timezone` | **Notes:** - Returns a downloadable attachment named `activeTournaments.csv`. - Response content type is CSV (`application/csv`). - `timezone` accepts an IANA timezone ID such as `Europe/London` or `America/New_York`. - If `timezone` is omitted, the `Start Time` and `Late Registration Ends` columns default to `America/Los_Angeles`. - `filter` accepts relative `Date` ranges; this resource uses the same network-endpoint semantics described under **Relative `Date` ranges** in section 3.5.10. **Parameters:** - `filter` - Optional active tournament filter string. - `limit` - Maximum number of tournaments to export. Must be `0` or greater. - `timezone` - Optional IANA timezone ID used to render the `Start Time` and `Late Registration Ends` columns. **Example:** ``` GET /api/someapp/networks/pokerstars/activeTournaments.csv?filter=Date:0S;Date!:600S&limit=100&timezone=Europe/London ``` #### 3.5.10 Active Tournaments Get currently active (registering, late-registering, or running) tournaments for one or more networks. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 (free for 1 minute) | | **Path** | `/activeTournaments` | | **Parameters** | `filter`, `limit` | **Notes:** - Full URL: `/api/{appname}/networks/{network}/activeTournaments`. - `network` may be a single network (`pokerstars`), a comma-separated list (`pokerstars,fulltilt`), or `*` for all networks. - Cost is waived (0) when the result set is empty. - Use relative `Date` constraints in `filter` to build time windows - see **Relative `Date` ranges** below. - Returns a `RegisteringTournaments` response payload (XML or JSON, selected via the `Accept` header). **Parameters:** - `filter` - Optional active tournament filter string. - `limit` - Optional maximum number of tournaments to return (`0` for no limit). **Example:** ``` GET /api/someapp/networks/pokerstars/activeTournaments?filter=Date:0S;Date!:600S&limit=100 ``` **Relative `Date` ranges:** A relative `Date` value is an **offset from "now"** - an integer followed by a unit: `Y` (year), `M` (month), `W` (week), `D` (day), `H` (hour), `S` (second). The integer may be negative. A plain (non-inverted) `Date` constraint keeps tournaments whose **scheduled start `>= now - offset`**. Because the offset is *subtracted*, a **negative** offset moves the threshold into the future: | Filter | Offset | Effective clause | Matches (active tournaments) | |---|---|---|---| | `Date:1D` | +86400 s | `start >= now - 1 day` | almost everything upcoming/running - not selective | | `Date:0S` | 0 s | `start >= now` | upcoming only (excludes already-running) | | `Date:-1D` | -86400 s | `start >= now + 1 day` | starting more than 24 h from now | Invert a constraint with `!` (placed before the colon) to set an **upper** bound on the start. On the network active-tournament endpoints the inverted form means **`start <= now + offset`**, so pair it with `Date:0S` to get a bounded window: | Filter | Matches | |---|---| | `Date:0S;Date!:600S` | starting in the next 10 minutes | | `Date:0S;Date!:1D` | starting within the next 24 hours | | `Date!:1D` | starting within 24 h **or already running** (no lower bound) | **Caveats:** - Tournaments with no scheduled start time, and those in **late registration**, are returned regardless of the `Date` constraint. - The per-player endpoint (section 3.3.3, `.../players/{player}/activeTournaments`) applies identical `Date`/`EndDate` semantics - the same offset rules, inverted `!` windows, and late-registration / unscheduled handling described here. --- #### 3.5.11 Tournament Player Edges Get the Tournament Edge for up to 20 named players in one registering tournament: each player's expected ROI and profit per entry if they entered it, built from that player's own record at this stake and format, the strength of the field, the overlay and the rake, with the likely range and the evidence behind it. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Gold and above, including the Pro plans) | | **Cost** | 1 for up to 20 players, spent only when at least one player was answered from a profile | | **Path** | `/{tournamentId}/edges` | | **Parameters** | `player` (repeatable), `players` | **Notes:** - Full URL: `/api/{appname}/networks/{network}/tournaments/{tournamentId}/edges`. One network only. - Registering tournaments only: a completed tournament has a result, not a forecast. - Name the players with repeated `player` parameters (exact, so a name containing a comma is safe) or one comma-separated `players` parameter. Up to 20 across both; repeats are ignored; more than 20 is refused. - A profile is the player's own results summarised by stake and format. It is built in the background from the player's results, never inside the request: a player nobody has asked about before is answered `NO_PROFILE` with `queued="true"`, and `retryAfterSeconds` on the response says when a second request will find it built. Such a request costs nothing; `charged` on the response says whether the search was spent. - Returns a `TournamentPlayerEdgesResponse` (XML or JSON, selected via the `Accept` header): one `Player` element per name, in the order asked. - On the PokerStars family of networks the figures on this resource include the field term, as the tournament page does; the tournament lists leave it out there. **Parameters:** - `player` - A player to answer for; repeat the parameter for several. - `players` - Players to answer for, comma-separated. **Example:** ``` GET /api/someapp/networks/pokerstars/tournaments/4025153795/edges?player=kbongrj&player=Alkazar99 GET /api/someapp/networks/pokerstars/tournaments/4025153795/edges?players=kbongrj,Alkazar99 ``` **Response attributes** (`TournamentPlayerEdgesResponse`): | Attribute | Meaning | |---|---| | `id`, `network`, `name`, `tournamentState` | The tournament asked about | | `queued` | How many players were answered `NO_PROFILE` and queued for a build | | `retryAfterSeconds` | When asking again is worth it; present when `queued` is above zero | | `charged` | Whether this request spent a search | Each `Player` element carries: | Attribute | Meaning | |---|---| | `player` | The player's name as SharkScope knows it (the name asked for, when nobody matched) | | `requested` | The name as asked for, only when it differs from `player` | | `state` | `OK` with a figure; `NO_PROFILE` (no profile yet; `queued="true"` when one was just queued); `STALE` (an old profile answered and a refresh is queued); `BEYOND_RECORD`, `DIFFERENT_GAME` or `NO_STAKE` (the record cannot price this tournament); `NOT_FOUND` (no such player on the network); `NOT_AVAILABLE` (the player's statistics are not shown) | | `roi`, `profit` | Expected ROI per entry in percent, and profit per entry in the tournament's currency | | `low`, `high`, `confidence` | The likely range, and `HIGH`, `MEDIUM` or `LOW` | | `baseline`, `games`, `profileAgeDays` | Which part of the record answered (`EXACT` stake and format, `BAND` stake only, `OVERALL`), the weighted games behind it, and the profile's age in days | | `termBaseline`, `termField`, `termOverlay`, `termRake` | The four terms; they add up to `roi` | | `fieldStrength`, `typicalFieldStrength` | The field's average ability and the usual one for this kind of game, when field data was available | | `fieldWithheld` | True when field data was withheld by network policy rather than missing | --- ### 3.6 Active Tournaments **Base Path:** `/api/{appname}/activeTournaments` #### 3.6.1 Players' Active Tournaments Get active tournaments for multiple players. | Property | Value | |----------|-------| | **Method** | GET/POST | | **Auth** | No | | **Cost** | 1 per player (free if queried <3h ago) | | **Path** | Root | | **Parameters** | `networkX`, `playerX` (X = 1, 2, 3...) | **Example:** ``` GET /api/someapp/activeTournaments?network1=pokerstars&player1=tom&network2=fulltilt&player2=jerry ``` --- ### 3.7 Leaderboard Resources **Base Path:** `/api/{appname}/poker-leaderboards` #### Hierarchy Navigation | Resource | Description | Cost | |----------|-------------|------| | `/{year}` | All leaderboards for year | 0 | | `/private` | All private leaderboards | 0 | | `/{year}/{category}` | Category hierarchy | 0 | | `/{year}/{category}/{subcategory}` | Subcategory hierarchy | 0 | | `/{...}/{value-type}` | Specific leaderboard with players | 0 | **Examples:** ``` GET /api/someapp/poker-leaderboards/2010 GET /api/someapp/poker-leaderboards/private GET /api/someapp/poker-leaderboards/2010/Scheduled GET /api/someapp/poker-leaderboards/2010/Scheduled/$16-$35 GET /api/someapp/poker-leaderboards/2010/Scheduled/$16-$35/total ``` --- ### 3.8 Network Resources **Base Path:** `/api/{appname}/networks/{network}` #### 3.8.1 Coverage Get network coverage information. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | No | | **Cost** | 0 | | **Path** | `/coverage` | **Network values:** - Specific network: `pokerstars` - Multiple: `pokerstars,fulltilt` - All: `*` **Examples:** ``` GET /api/someapp/networks/pokerstars/coverage GET /api/someapp/networks/pokerstars,fulltilt/coverage GET /api/someapp/networks/*/coverage ``` --- ### 3.9 User Resources **Base Path:** `/api/{appname}/user` #### 3.9.1 Login Verify authentication. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | Root | #### 3.9.2 Preferences Get user preferences. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/preferences` | #### 3.9.3 Blog URL Get/set/delete blog URL (for personal groups). | Property | Value | |----------|-------| | **Method** | GET/DELETE | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/blogurl` | | **Parameters** | `value` (URL-encoded) | #### 3.9.4 User Metadata Get user-specific metadata. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Optional | | **Cost** | 0 | | **Path** | `/metadata` | #### 3.9.5 Preferences Update Update preference values. | Property | Value | |----------|-------| | **Method** | GET/POST | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/preferences/update` | | **Parameters** | Key-value pairs (empty = delete) | **Example:** ``` GET /api/someapp/user/preferences/update?Currency=USD&Pref1=123.4&Pref2= ``` #### 3.9.6 Payments Get payment history. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/payments` | #### 3.9.7 Creation/Registration Create new user account. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required* | | **Cost** | 0 | | **Path** | `/create` | | **Parameters** | `affID`, `country`, `emailOption` | ***Password:** Single MD5 hash only (not double-encoded) #### 3.9.8 Saved Filters Manage saved filter definitions. | Resource | Method | Description | |----------|--------|-------------| | `/filters` | GET | List all saved filters | | `/filters/{name}` | GET | Get specific filter | | `/filters/{name}/save` | GET | Save filter | | `/filters/{name}/delete` | GET | Delete filter | **Parameters:** `type` (Player/Tournament/All), `text` (for save) **Examples:** ``` GET /api/someapp/user/filters GET /api/someapp/user/filters/MyFilter GET /api/someapp/user/filters/MyFilter/save?type=Player&text=Date:1Y GET /api/someapp/user/filters/MyFilter/delete ``` #### 3.9.9 Account Management Change email address or password. | Resource | Method | Parameters | Description | |----------|--------|------------|-------------| | `/change` | GET | `newemail` | Change email | | `/change` | GET | `newpassword` | Change password | **Examples:** ``` GET /api/someapp/user/change?newemail=newemail@example.com GET /api/someapp/user/change?newpassword=newhashedpassword ``` #### 3.9.10 Player Classes Manage user-specific and user-defined player classes. | Resource | Method | Description | |----------|--------|-------------| | `/playerclasses` | GET | Get user-specific classes | | `/playerclasses/defined` | GET | Get user-defined classes | | `/playerclasses/defined/{name}` | GET | Create/modify class | | `/playerclasses/defined/{name}` | DELETE | Delete class | **Create/Modify Parameters:** - `priority` - Sort order - `rules` - Semicolon-separated `stat:min~max` (use `*` for any) - `icon` - Icon URI - `categories` - Semicolon-separated categories - `currency` - Currency code **Examples:** ``` GET /api/someapp/user/playerclasses GET /api/someapp/user/playerclasses/defined GET /api/someapp/user/playerclasses/defined/Fish?priority=40&rules=Count:50~*;AvProfit:*~0;AvROI:*~-20&icon=images/Fish.gif¤cy=USD&categories=Fish DELETE /api/someapp/user/playerclasses/defined/Fish ``` #### 3.9.11 Reseller Manage reseller information and payments. | Resource | Method | Description | |----------|--------|-------------| | `/reseller` | GET | Get reseller info | | `/reseller/payment` | GET | Add subscription to user | | `/reseller/payment/preview` | GET | Preview a prospective sale before committing it | | `/reseller/payment/edit` | GET | Change the role on a sale already made | | `/reseller/payment/remove` | GET | Remove a sale | **Parameters:** - `userEmail`, `roleID` - the customer and the subscription role, for `payment` and `payment/preview` - `txnID`, `itemIndex` - identify the existing sale, for `payment/edit` and `payment/remove` - `roleID` - the replacement role, for `payment/edit` **Examples:** ``` GET /api/someapp/user/reseller GET /api/someapp/user/reseller/payment/preview?userEmail=user@example.com&roleID=341 GET /api/someapp/user/reseller/payment?userEmail=user@example.com&roleID=341 GET /api/someapp/user/reseller/payment/edit?txnID=SS-1234&itemIndex=0&roleID=342 GET /api/someapp/user/reseller/payment/remove?txnID=SS-1234&itemIndex=0 ``` #### 3.9.12 Application Permissions Manage user permissions for applications (admin only). | Resource | Method | Description | |----------|--------|-------------| | `/{app}/users/{user}/permission` | PUT | Set permission | | `/{app}/users/{user}/permission` | GET | Get permission | | `/{app}/users/{user}/permission` | DELETE | Delete permission | **Set Parameters:** `expiry` (Unix timestamp, optional - null = perpetual) **Examples:** ``` PUT /api/someapp/users/someone@aol.com/permission?expiry=1407542400 GET /api/someapp/users/someone@aol.com/permission DELETE /api/someapp/users/someone@aol.com/permission ``` #### 3.9.13 User Notes (Bulk) Get/set/delete notes for multiple players. | Property | Value | |----------|-------| | **Method** | GET/POST | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/notes` | | **Parameters** | `notes` (POST: network, player, notes, `.` separator) | **Examples:** ``` GET /api/someapp/user/notes POST /api/someapp/user/notes ``` #### 3.9.14 Manager Manage account managers (can view email, subscription, player names). | Resource | Method | Parameters | Description | |----------|--------|------------|-------------| | `/manager` | GET | `value=email` | Set manager | | `/manager` | DELETE | - | Delete manager | | `/secondarymanager` | GET | `value=email` | Set secondary (subscribers) | | `/secondarymanager` | DELETE | - | Delete secondary | **Examples:** ``` GET /api/someapp/users/manager?value=manager@gmail.com DELETE /api/someapp/users/manager GET /api/someapp/users/secondarymanager?value=manager2@gmail.com DELETE /api/someapp/users/secondarymanager ``` #### 3.9.15 Usage History Get search usage breakdown. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 1 search | | **Path** | `/usageHistory` | **Note:** Updates every few minutes --- ### 3.10 Report Resources #### 3.10.1 Market Share Reports Get market share reports by region or network. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | Access by agreement only | **Cost** | 0 | | **Path** | `/reports/marketshare/regions/{region}` | | | `/reports/marketshare/networks/{network}` | | **Parameters** | `year`, `month`, `type` (SNGEntrants/MTTEntrants) | **Examples:** ``` GET /api/someapp/reports/marketshare/regions/FR?type=MTTEntrants&year=12&month=12 GET /api/someapp/reports/marketshare/networks/pokerstars?type=MTTEntrants&year=12&month=12 ``` #### 3.10.2 Hourly Market Share Reports Get hourly scheduled tournament data by region or network. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | Access by agreement only | **Cost** | 0 | | **Path** | `/reports/hourlymarketshare/regions/{region}` | | | `/reports/hourlymarketshare/networks/{network}` | | **Parameters** | `date` (YYYY-MM-DD) | **Examples:** ``` GET /api/someapp/reports/hourlymarketshare/regions/FR?date=2014-11-31 GET /api/someapp/reports/hourlymarketshare/networks/pokerstars?date=2014-11-31 ``` #### 3.10.3 Daily Scheduled Tournaments Reports Get daily scheduled tournament list by region or network. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Commercial Gold+) | | **Cost** | 0 | | **Path** | `/reports/dailyscheduledtournaments/regions/{region}` | | | `/reports/dailyscheduledtournaments/networks/{network}` | | **Parameters** | `date` (YYYY-MM-DD, Pacific timezone) | **Availability:** Last 3 days **Data Source:** Scheduled tournaments snapshot ellites <$15 **Examples:** ``` GET /api/someapp/reports/dailyscheduledtournaments/regions/FR?date=2014-11-31 GET /api/someapp/reports/dailyscheduledtournaments/networks/pokerstars?date=2014-11-31 ``` #### 3.10.4 Network Overview Report Returns daily network-level cash and scheduled tournament activity for the requested date range. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | Access by agreement only | **Cost** | 0 | | **Path** | `/reports/networkoverview/networks/{network}` | | **Parameters** | `startDate` (YYYY-MM-DD, optional), `endDate` (YYYY-MM-DD, optional) | **Default Range:** If no dates are supplied, the report returns the last 7 days inclusive. If only one bound is supplied, the other is inferred to produce a 7-day window or uses today as the end date. **Response Notes:** - The response is grouped by day. - Each `Day` contains nested `Network` elements. - `averageSeatedCashPlayers` is the daily seated-player average rounded to the nearest whole number. - Values may be absent for networks with no recorded data on a given day. **Examples:** ``` GET /api/someapp/reports/networkoverview/networks/pokerstars?startDate=2026-01-06&endDate=2026-01-15 GET /api/someapp/reports/networkoverview/networks/* ``` **Example Response:** ```xml ``` --- ### 3.11 Filter Filter strings select tournaments by the `Type` constraint, among others. These are the codes `Type` accepts. #### Type Options (Complete List) | Code | Category | Name | Description | |------|----------|------|-------------| | **Formats** | | | | | TR | Format | Tiered | The prize is a ticket to the next tournament tier. Also known as Step tournaments | | DM | Flag | Deal Made | A deal was made in this tournament | | M | PrizeStructure | Matrix | 4 simultaneous Sit&Goes against the same players, with additional prizes for overall performances | | B | PrizeStructure | Bounty | Additional prizes are given for knocking players out. Also known as Knockout, Hitman and HeadHunter tournaments | | SO | Format | Shootout | Only the winner of each table progresses | | OD | Format | OnDemand | Sit & Gos with Late Registration | | HU | Format | Heads Up | 2 players per table | | FO | Format | Flipout | All in initially and the survivors play for the money | | R | Format | Rebuy | The tournament allows rebuys or add-ons | | DN | PrizeStructure | Double or Nothing | Half of the players double their buy in | | FPP | Format | FPP | The tournament buy in is with frequent player points | | J | PrizeStructure | Jackpot | Additional rake goes towards a grand prize | | K | PrizeStructure | Killer | No prizepool just a full bounty on each player | | TN | PrizeStructure | Triple or Nothing | 1/3rd of the players triple their buy in | | W | PrizeStructure | Winner Takes All | 1st place wins the entire prize pool | | C | PrizeStructure | Cashout | Players can cash in their tournament chips at any time | | RH | Format | Rush | When players fold, they are transferred to a new table and dealt a new hand | | SAT | Format | Satellite | Prize is an entry into another tournament | | TI | PrizeStructure | Timed | The tournament finishes at a set time | | NS | Format | N-Stack | Players can choose when to use each of their stacks in the tournament | | F | PrizeStructure | Fifty50 | Half the field paid based on chip counts | | HIT | PrizeStructure | Hit&Run | Passing a chip threshold instantly awards a ticket | | ME | Format | Multi Entry | Players can register more than once and play multiple tables | | **Speed** | | | | | T | Speed | Turbo | Blinds level increase faster than normal | | ST | Speed | Super Turbo | Blind levels increase faster than in a Turbo tournament | | D | Speed | Deep Stack | Starting stacks are larger than normal | | NBI | Speed | No Blind Increases | Static blind levels for the entirety of the tournament | | L | Speed | Lottery | All players are automatically put All In at the start | | N | Speed | Normal | Blinds level increase at normal rate | | **Multi-Day** | | | | | D1 | MultiDay | Day 1 | Qualifier / Day 1 flight tournaments| | FD | MultiDay | Final Day | Final-day tournaments | | **Structure** | | | | | NL | Structure | No Limit | | | PL | Structure | Pot Limit | | | PNL | Structure | PNL | | | FL | Structure | Limit | | | SL | Structure | Spread Limit | | | ML | Structure | Mixed Limit | | | **Games** | | | | | FU | Game | Fusion | | | H | Game | Hold'em | | | RV | Game | Reverse Holdem | | | H6 | Game | Six-Plus Holdem | | | SH | Game | Showtime Holdem | | | SHO | Game | Showtime Omaha | | | OMAHA | Game | Any Omaha | Includes O, OHL, O5, OHL5, CL, CLHL | | O | Game | Omaha Hi | | | OHL | Game | Omaha H/L | | | O5 | Game | Omaha 5 | | | OHL5 | Game | Omaha 5 H/L | | | O6 | Game | Omaha 6 | | | CL | Game | Courchevel | | | CLHL | Game | Courchevel H/L | | | CP | Game | Crazy Pineapple | | | POFC | Game | Pineapple | | | STUD | Game | Any Stud | Includes 7CS, 7CSHL, 5CS, RAZZ, A, S | | TS | Game | Triple Stud | | | 7CS | Game | 7 Card Stud | | | 7CSHL | Game | 7 Card Stud H/L | | | 5CS | Game | 5 Card Stud | | | RAZZ | Game | Razz | | | A | Game | Americana | | | S | Game | Soko | | | DRAW | Game | Any Draw | Includes 5CD, BA, TD27L, SD27L, 32D | | 5CD | Game | 5 Card Draw | | | BA | Game | Badugi | | | TD27L | Game | 2-7 Triple draw | | | SD27L | Game | 2-7 Single Draw | | | 32D | Game | 32 Draw | | | MIXED | Game | Any Mixed | Includes HORSE, HEROS, HOSE, RASH, HA, HAR, SHOE, TE, 8G, 7G | | HORSE | Game | HORSE | | | HEROS | Game | HEROS | | | HOSE | Game | HOSE | | | RASH | Game | RASH | | | HA | Game | HA | | | HAR | Game | HAR | | | SHOE | Game | SHOE | | | TE | Game | Telesina | | | 8G | Game | 8-Game | | | 7G | Game | 7-Game | | | 10G | Game | 10-Game | | | HBJ | Game | Holdem BJ | | | HO | Game | HO | | | I | Game | Irish Holdem | | | **Difficulty** | | | | | Easy | Difficulty | Easy Tournament | | | Neutral | Difficulty | Neutral Tournament | | | Hard | Difficulty | Hard Tournament | | | **Table Size** | | | | | 6MX | TableSize | 6 Max | 6 players per table | | HU | TableSize | Heads Up | 2 players per table | --- ### 3.12 Natural Language Query Convert natural language to filter (any language). Natural language queries can produce any supported filter constraint, including `Tables` for requests about tournament table count. `ReEntries` and `OverrideReEntries` are distinct: - `ReEntries` filters tournaments by the player's actual tracked re-entry count. - `OverrideReEntries` is a stats-only override used when the caller wants to assume a specific re-entry count for networks that do not track per-player multi-entry counts. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 1 search | | **Path** | `/networks/{network}/players/{player}` | | **Parameters** | `nlq`, `timezone`, `currency` | **Example Queries:** - "Last 50 no limit Bounty tournaments during May, exclude Super Turbos" - "Tournaments played on weekends" - "Biggest 10 tournaments where I final tabled and made 0 Re-entries" - "Assume 0 re-entries for unknown multi-entry tournaments" - "Show me my best 10 tournaments from last year" - "Tournaments where I played against PokerTom" - "Tournament results with highest ROI when I did not final table" - "Tournaments with 10 or more tables" - "Final day tournaments from last summer" **Example:** ``` GET /api/someapp/networks/fulltilt/players/tom?nlq=Tournament%20Results%20with%20the%20Highest%20ROI%20where%20I%20didn%27t%20final%20table&timezone=America/Los_Angeles&Currency=USD ``` **Response:** May include `nlqUnsupportedMessage` attribute if partially supported --- ### 3.12.1 Natural Language Filter Conversion Convert natural language to a SharkScope filter object. This conversion can emit the `Tables` constraint for requests about how many tables a tournament had. It can also emit `OverrideReEntries` when the question explicitly asks to assume a specific re-entry count for untracked multi-entry calculations, while `ReEntries` remains the actual-count tournament filter. | Property | Value | |----------|----------------------------------| | **Method** | GET | | **Auth** | Required (Subscriber) | | **Cost** | 1 search | | **Path** | `/filters/nlq` | | **Parameters** | `question`, `timezone`, `locale` | **Example:** ``` GET /api/someapp/filters/nlq?question=Last%2050%20bounty%20tournaments%20in%20May&timezone=America/Los_Angeles&locale=en ``` **Response:** Returns `Filter` (a `PlayerTournamentFilter`) plus `Unsupported` text if the query is partially or fully unsupported. --- ### 3.13 Missing Games Resources #### 3.13.1 Missing Games by IDs Report missing PokerStars tournaments by ID. | Property | Value | |----------|-------| | **Method** | POST | | **Auth** | No | | **Cost** | 0 | | **Path** | `/networks/{network}/reportmissinggames` | | **Parameters** | `gameids` (form parameter) | **Response:** ```xml ``` **Statuses:** `processed`, `pending`, `existing`, `error` #### 3.13.2 Missing Games by Summary Report missing games via PokerStars email summary. | Property | Value | |----------|-------| | **Method** | POST | | **Auth** | No | | **Cost** | 0 | | **Path** | `/reportmissinggamesbysummary` | | **Body** | Plain text tournament summary from email | **Example Summary:** ``` Tournament History for Tournament #1 requested by User (email@example.com) PokerStars Tournament #1234578820, No Limit Hold'em Buy-In: $2.82/$0.18 USD 3 players Total Prize Pool: $6.00 USD Tournament started 2015/08/27 17:24:39 ET Tournament finished 2015/08/27 17:40:14 ET 1: Winner (Netherlands), $6.00 (100%) 2: Second (Luxembourg), 3: Third (Finland), ``` #### 3.13.3 List PokerCraft Permitted Viewers List email addresses of accounts permitted to view your private PokerCraft uploads. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/user/permittedViewers` | **Example:** ``` GET /api/someapp/user/permittedViewers ``` #### 3.13.4 Add PokerCraft Permitted Viewer Add account that can view your private PokerCraft uploads. | Property | Value | |----------|-------| | **Method** | PUT | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/user/permittedViewers/{email}` | **Note:** Email must correspond to existing SharkScope account. **Example:** ``` PUT /api/someapp/user/permittedViewers/example@example.com ``` #### 3.13.5 Remove PokerCraft Permitted Viewer Remove account's permission to view your private PokerCraft uploads. | Property | Value | |----------|-------| | **Method** | DELETE | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/user/permittedViewers/{email}` | **Example:** ``` DELETE /api/someapp/user/permittedViewers/example@example.com ``` #### 3.13.6 Upload PokerCraft Data Upload PokerCraft report file. | Property | Value | |----------|-------| | **Method** | POST | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/reportmissinggames/pokerCraftUpload` | | **Parameters** | `file` (multipart), `timezoneoffset`, `playername`, `privacy` (default: private) | #### 3.13.7 Request PokerCraft Name Transfer Request transfer of alias from old GG player to new GG player. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/reportmissinggames/pokerCraftUpload/requestNameTransfer` | | **Parameters** | `previousName`, `newName`, `confirmed` (default: false) | #### 3.13.8 List Uploaded PokerCraft Data List uploaded PokerCraft files. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/reportmissinggames/pokerCraftUpload/list` | | **Parameters** | `date`, `player`, `network`, `file`, `limit` (default: 100), `offset` (default: 0) | #### 3.13.9 List PokerCraft Players List players found in uploaded PokerCraft data. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/reportmissinggames/pokerCraftUpload/players` | #### 3.13.10 Update PokerCraft Player Privacy Update privacy setting for a specific player in PokerCraft uploads. | Property | Value | |----------|-------| | **Method** | POST | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/reportmissinggames/pokerCraftUpload/player/{player}/privacy` | | **Parameters** | `network`, `privacy` (form param) | #### 3.13.11 Delete Specific PokerCraft Upload Delete a specific PokerCraft upload by ID. | Property | Value | |----------|-------| | **Method** | DELETE | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/reportmissinggames/pokerCraftUpload/{id}` | #### 3.13.12 Delete PokerCraft Player Uploads Delete all uploads for a specific player. | Property | Value | |----------|-------| | **Method** | DELETE | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/reportmissinggames/pokerCraftUpload/player/{player}` | | **Parameters** | `network` | --- ### 3.14 Deal Resources **Base Path:** `/api/{appname}/deals/{dealname}` #### 3.14.1 Activation Activate a deal (use `signup` or `*` for signup deals). | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/activate` | | **Parameters** | `id` (unique device/license), `activationCode` | **Activation Code Generation:** ``` MD5(MD5(username + uniqueID).toLowerCase() + applicationKey.toLowerCase()) ``` **Java Example:** ```java String username = "someone@somewhere.com"; String uniqueID = "1234567890"; String applicationKey = "21f5e7aa7893caf0"; String code = (username + uniqueID).toLowerCase(); String key = code + applicationKey.toLowerCase(); MessageDigest md = MessageDigest.getInstance("MD5"); md.update(key.getBytes()); byte[] digest = md.digest(); StringBuffer hex = new StringBuffer(); for (byte b : digest) { int val = 0xFF & b; if (val < 16) hex.append('0'); hex.append(Integer.toHexString(val)); } return hex.toString().toLowerCase(); ``` --- ### 3.15 Private Leaderboard Resources **Base Path:** `/api/{appname}/user/private-leaderboards` **Limits:** 3 leaderboards per account, 100 entrants each (Gold subscribers) #### Resource Overview | Resource | Method | Auth | Description | |----------|--------|------|-------------| | Root | GET | Required | List all private leaderboards | | `/create` | GET | Required (Gold) | Create new leaderboard | | `/{id}/edit` | GET | Required (Gold) | Edit leaderboard | | `/{id}` | DELETE | Required | Delete leaderboard | | `/{id}/enable` | GET | Required | Enable/publish leaderboard | | `/{id}/disable` | GET | Required | Disable/unpublish leaderboard | | `/{id}/{network}/{player}` | GET | Required | Add entrant | | `/{id}/{network}/{player}` | DELETE | Required | Remove entrant | **Create Parameters:** - `name` - Unique name - `filter` - Tournament filter - `rankingstatistic` - Stat to rank by (e.g., Profit) - `currency` - Currency code - `mingamesfordisplay` - Min games to display (optional) **Edit Parameters:** Same as create (all optional) --- ### 3.16 Stable Resources #### 3.16.1 Get Stable List users who have assigned you as manager. | Property | Value | |----------|-------| | **Method** | GET | | **Auth** | Required | | **Cost** | 0 | | **Path** | `/stable` | --- ### 3.17 Tracking Outage Resources #### Get Outages | Resource | Description | |----------|-------------| | `/system-status/open` | Current open outages | | `/system-status/recent` | Last 3 months (open + closed) | **Properties:** - Method: GET - Auth: No - Cost: 0 ### 3.18 Tournament Calendar Resources **Base Path:** `/api/{appname}/tournamentlabels` A label is a named, coloured, optionally nested collection of tournaments. It picks up members two ways: by hand, and by rule - a saved filter that keeps applying the label to matching events as rooms announce them. Labels are what make the forward schedule readable: six networks alone list around four thousand tournaments in any twenty-four hours. Reading labels costs no searches - the responses come from stored rows and the in-memory forward schedule, and never touch tournament results. How many labels and rules an account may hold depends on its subscription tier; the limits come back with the labels response. #### 3.18.1 Labels | Resource | Method | Description | |----------|--------|-------------| | `/` | GET | Every label you own, with its hand-applied members and rules | | `/create` | GET | Create a label | | `/{id}/update` | GET | Rename, recolour, re-parent or reorder a label | | `/{id}/delete` | GET | Delete a label | **Properties:** - Auth: Required - Cost: 0 **Parameters:** - `counts` (list) - `true` to include how many tournaments each label currently claims - `name`, `colour`, `parentID` (create) - `colour` may be omitted, in which case the next unused hue from the palette is used; `parentID` nests the label under another - `name`, `colour`, `parentID`, `sortOrder` (update) **Examples:** ``` GET /api/someapp/tournamentlabels?counts=true GET /api/someapp/tournamentlabels/create?name=Sunday%20Majors&colour=%23c8102e GET /api/someapp/tournamentlabels/12/update?name=Sunday%20Grind&sortOrder=2 GET /api/someapp/tournamentlabels/12/delete ``` **Response:** `TournamentLabelsResponse` #### 3.18.2 Label Members | Resource | Method | Description | |----------|--------|-------------| | `/{id}/add` | GET | Apply the label to a tournament, or to the recurring event behind it | | `/{id}/remove` | GET | Take the label off again | | `/eventpreview` | GET | What following a recurring event would collect, before anything is written | | `/forgames` | GET | Which of your labels claim each of the named tournaments | **Properties:** - Auth: Required - Cost: 0 **Parameters:** - `network`, `gameID` or `typeID` - identify the tournament. A game identifier is unique only within its own network, so the network is always required - `scope` - `series` (default) labels the recurring event, so later runnings are picked up too; `game` labels only the one tournament - `muted` (add) - `true` to exclude a tournament a rule would otherwise claim - `games` (forgames) - the tournaments to ask about, as `network~gameID,gameID|network~gameID`. The list is capped, so ask about a visible page rather than a whole result set **Notes:** - Tournament listings carry no label information, so a page of tournaments cannot show which of them are already on a calendar without asking `/forgames` separately. - `/eventpreview` reports `resolvable=false` where the room publishes no type for the game, in which case the event cannot be followed forward at all. Matching is multi-entry agnostic, so an event split across two type identifiers by a re-entry capture is counted once and followed as one event. **Examples:** ``` GET /api/someapp/tournamentlabels/12/add?network=PokerStars&gameID=1250001&scope=series GET /api/someapp/tournamentlabels/12/remove?network=PokerStars&gameID=1250001 GET /api/someapp/tournamentlabels/eventpreview?network=PokerStars&gameID=1250001 GET /api/someapp/tournamentlabels/forgames?games=PokerStars~1250001,1250002|Chico~984-8665d2 ``` **Response:** `TournamentLabelsResponse`, `TournamentLabelPreviewResponse` (eventpreview) or `TournamentLabelGamesResponse` (forgames) #### 3.18.3 Label Rules A rule keeps applying its label to tournaments announced later, so it is worth knowing what an expression claims before it is stored. | Resource | Method | Description | |----------|--------|-------------| | `/rulepreview` | GET | How many tournaments on the forward schedule a candidate rule would claim | | `/{id}/rules/create` | GET | Add a rule to a label | | `/{id}/rules/{ruleid}/update` | GET | Change or disable a rule | | `/{id}/rules/{ruleid}/delete` | GET | Delete a rule | **Properties:** - Auth: Required - Cost: 0 - counting runs against the same forward schedule the calendar renders from, which is held in memory **Parameters:** - `filter` - a tournament filter string, validated exactly as creating a rule validates it - `networks` - comma-separated network names to restrict the rule to - `enabled` (update) - `true` (default) or `false` **Notes:** - Counting stops at five hundred matches; `capped` is set when it does, so the number is a floor rather than a total. **Examples:** ``` GET /api/someapp/tournamentlabels/rulepreview?filter=Stake:USD10.00~USD120.00;Class:SCHEDULED&networks=PokerStars,partypoker GET /api/someapp/tournamentlabels/12/rules/create?filter=Stake:USD10.00~USD120.00&networks=PokerStars GET /api/someapp/tournamentlabels/12/rules/44/update?enabled=false GET /api/someapp/tournamentlabels/12/rules/44/delete ``` **Response:** `TournamentLabelsResponse`, or `TournamentLabelPreviewResponse` for `rulepreview` #### 3.18.4 Label Alerts An alert is set once per label and applies to every event that label picks up, so a rule that keeps applying the label keeps the alert applying too. | Resource | Method | Description | |----------|--------|-------------| | `/{id}/alerts` | GET | The alert policy on the label, and the alerts it recently produced | | `/{id}/alerts/save` | GET | Create or update the policy for one trigger | | `/{id}/alerts/{ruleid}/delete` | GET | Delete one trigger's policy | | `/{id}/alerts/acknowledge` | GET | Mark delivered alerts as read | **Properties:** - Auth: Required (Subscriber) - Cost: 0 **Parameters:** - `trigger` (save) - `starting`, `lateregclosing` or `didnotrun` - `enabled` (save) - `true` (default) or `false` - `channels` / `digestChannels` - comma-separated destination ids, delivered as they fire or rolled into a digest. The in-app feed is always included whatever you send - `leadMinutes`, `softerBy`, `abilityBelow`, `minEntrants`, `overlayPct` - trigger-specific thresholds - `ruleID` (acknowledge) - optional; acknowledges one trigger instead of every alert on the label **Examples:** ``` GET /api/someapp/tournamentlabels/12/alerts GET /api/someapp/tournamentlabels/12/alerts/save?trigger=starting&leadMinutes=60&channels=12 GET /api/someapp/tournamentlabels/12/alerts/acknowledge ``` **Response:** `PlayerGroupAlertsResponse` --- ## 4. Response Objects ### 4.1 Metadata **Contains:** - FilterDefinition - Regions - Networks - Currencies - PlayerStatisticsDefinitions - TournamentStatisticsDefinitions - DefaultPlayerClasses #### Network Object ```xml 1234567890 98.5 5 1100000000 50000000 Full PokerStars.it PokerStars.es ``` #### Currency Object ```xml ``` #### Statistic Definition ```xml ``` #### Statistical Dataset Definition ```xml ``` ### 4.2 UserMetadata #### SavedFilter ```xml Class:SNG Entrants:5~10 ``` ### 4.3 Player #### Player Object ```xml 2198 7.78 17091.70 ``` #### PlayerGroup Object ```xml ``` #### Statistics with Dataset ```xml 2198 -118.00 -76.62 7 60.00 90.91 3 ``` ### 4.4 Tournament Tournament objects contain: - Tournament details (ID, name, network, dates, stake, rake) - Completed tournament responses may also include a `multiday` attribute with the values `qualifier`, `final`, or `combined`/omitted when the tournament is not classified as multi-day - Statistics (if requested) - TournamentEntry objects (player results) - `TournamentPlayerEdgesResponse` (section 3.5.11) carries one `Player` element per name asked about, with the edge attributes listed there ### 4.5 Leaderboards #### Hierarchy Response ```xml ``` #### Leaderboard with Players ```xml ``` --- ## 5. Errors ### Error Response Format ```xml ... Invalid password. ``` ### Error Code Categories | Range | Category | |-------|----------| | 0 | Internal errors | | 101xxx | User errors | | 102xxx | Search quota errors | | 103xxx | Player class errors | | 105xxx | Player group errors | | 106xxx | Leaderboard errors | | 107xxx | Bonus code errors | | 200xxx | Request errors | | 201-204xxx | System and filter errors | | 300-301xxx | Order/notification errors | | 400xxx | Authorization errors | ### Common Error Codes | Code | Description | |------|-------------| | **Authentication** | | | 101001 | User not found | | 101002 | Invalid password | | 101003 | No username or password supplied | | 101013 | Invalid username (must be valid email) | | 200001 | Authentication failure | | **Quota** | | | 102001 | Free daily searches quota used up | | 102002 | Daily searches quota used up | | 102004 | Operation only allowed for subscribers | | 102005 | Operation only allowed for gold subscribers | | 102007 | No searches left | | 102013 | Operation only allowed for Commercial Gold | | **Player/Network** | | | 200003 | Network not found | | 200004 | Player not found or opted out | | 200012 | Tournament not found | | 200019 | Player is opted out | | **Filter** | | | 202002 | Filter not valid | | 204001 | Unknown filter constraint | | 204003 | Invalid value(s) for filter constraint | | **Groups** | | | 105001 | Player group not found | | 105004 | Player group already exists | | 105006 | Player already in group | | 105009 | Cannot add blocked players to groups | | 105013 | Max player group size reached | | **Authorization** | | | 400001 | No authorization for this action | | 400002 | Player not opted in | | 400004 | Access to this network is not authorized | | **System** | | | 201003 | Server is busy. Try again later | | 200044 | Database currently under maintenance | ### Complete Error Code Reference | Error ID | Description | |----------|-------------| | **Internal Errors** | | | 0 | Internal error | | **User Errors (101xxx)** | | | 101001 | User not found | | 101002 | Invalid password | | 101003 | No username or password supplied | | 101004 | User already exists | | 101005 | User \ already registered | | 101006 | Failed to create user | | 101007 | Failed to change the email | | 101008 | Invalid email address | | 101009 | An account already exists with this Email address | | 101010 | Failed to change the password | | 101011 | User-Agent header not specified | | 101012 | Request information is not valid | | 101013 | Invalid username (must be a valid email address) | | 101014 | Order number not found | | 101015 | Password email dispatch failed | | 101016 | User cannot be deleted as they have payment entries registered to this account | | 101017 | Too many players already reset on this network. Resets are only to be used on your own player names. Remove resets created on other player names before you can add new ones | | 101018 | Too many players already reset on this network. Resets are only to be used on your own player names. Remove resets created on other player names before you can add new ones | | 101024 | Account is logged in elsewhere | | 101025 | This user has not assigned you as their manager | | 101026 | A password reset request email has already been sent recently. Please try again later | | **Search Quota Errors (102xxx)** | | | 102001 | Free daily searches quota used up | | 102002 | Daily searches quota used up | | 102003 | Pay-as-you-go searches used up | | 102004 | Operation only allowed for subscribers | | 102005 | Operation only allowed for gold subscribers | | 102006 | Remaining Search Quota too low | | 102007 | No searches left | | 102008 | No free searches left. Subscribe now to continue exploring! | | 102009 | Not ready for next search | | 102010 | Complex operations not allowed without subscription | | 102011 | Operation only allowed for Platinum subscribers | | 102012 | The user who created the reset must be a subscriber | | 102013 | Operation only allowed for Commercial Gold subscribers | | 102014 | Operation only allowed for Commercial subscribers | | **Player Class Errors (103xxx)** | | | 103001 | Invalid player class name | | 103002 | Invalid player class priority | | 103003 | Invalid player class rules | | 103004 | Player class not found | | 103005 | Player class update failed | | 103006 | Invalid player class currency | | **Player Group Errors (105xxx)** | | | 105001 | Player group not found | | 105002 | Invalid player group name | | 105003 | No valid player group members specified | | 105004 | Player group already exists | | 105005 | Player not valid member for group | | 105006 | Player already in group | | 105007 | The group may be modified only by its owner | | 105008 | The maximum number of players allowed for this network have already been added to your personal group | | 105009 | Cannot add blocked players to groups | | 105010 | Personal group not configured | | 105011 | At least one member must be opted in | | 105012 | Player Group query returns too much data. Please use a non consolidated group, a more restrictive search filter or reduce the size of the group | | 105013 | Max player group size reached. For Groups larger than 25 players please switch to a Commercial Subscription | | **Leaderboard Errors (106xxx)** | | | 106001 | Maximum number of private leaderboards already exist | | 106002 | Private leaderboard contains maximum number | | 106003 | A private leaderboard with that name already exists | | 106004 | This player is blocked from being entered into leaderboards | | 106005 | This operation can only be performed on private leaderboards | | 106006 | This player is already in at least one leaderboard | | 106007 | This player was recently checked to see if they qualified for any leaderboards. Please try again later | | 106008 | The leaderboard end date is too far in the future | | **Bonus Code Errors (107xxx)** | | | 107001 | Unknown Bonus Code | | 107002 | Bonus Code Expired | | 107003 | Bonus Code Used Up | | 107004 | Bonus Code Not Applicable | | 107005 | Bonus Code not started yet | | 107006 | Bonus Code is only for new users | | **Request Errors (200xxx)** | | | 200001 | Authentication failure | | 200002 | No valid statistics requested | | 200003 | Network not found | | 200004 | Player not found or opted out | | 200005 | Invalid player name prefix | | 200006 | Invalid native currency | | 200007 | Invalid display currency | | 200008 | Invalid tournament limit | | 200009 | Invalid mode | | 200010 | Leaderboard not found | | 200011 | Leaderboards not found | | 200012 | Tournament not found | | 200013 | Request not allowed on all networks | | 200014 | There is no installer/updater for this application | | 200015 | Application not found | | 200016 | Valid download types are "installer" and "updater" | | 200017 | Invalid currency | | 200018 | Request not allowed on multiple users | | 200019 | Player is opted out | | 200020 | Invalid URL | | 200021 | You must enter a valid number for this parameter | | 200025 | Missing parameter | | 200026 | Opt Out request failed. Please contact support@sharkscope.com if the problem persists | | 200027 | Opt In request failed. Please contact support@sharkscope.com if the problem persists | | 200028 | This player has already been reset by another user | | 200029 | Blocks are not allowed on this network | | 200030 | Player belongs to one or more leaderboards | | 200031 | Player is not opted out | | 200032 | To unblock the user you must use the same email address as was used to block it | | 200033 | Unknown confirmation request | | 200034 | Too many usernames blocked on this network | | 200035 | Report not found | | 200036 | Unknown report type | | 200037 | Network has its own Opt/Out procedure | | 200038 | Reset date must be in the past | | 200039 | Player group not found | | 200040 | Player is not a member of the group | | 200044 | The \ database is currently under maintenance. Please try again later | | 200045 | Unknown graph type | | 200046 | Invalid tournament id | | 200047 | Invalid Video ID | | 200048 | User must be logged-in using their username and password | | 200049 | Remove Optin request failed | | 200050 | Unknown region | | 200052 | Player not in tournament | | 200053 | Report Missing Tournaments is not allowed on this network | | 200054 | Timeline event not found | | 200055 | Timeline request not found | | 200056 | This is not your timeline request | | 200057 | Operation not allowed for this network | | 200058 | Tournament table not found | | 200059 | Country not found | | 200060 | Players in achievement races cannot opt out | | 200061 | Empty results, no missing tournament found | | 200062 | Empty results, no tournament rebuy information found | | 200063 | Rebuy count is below 0 | | 200064 | Rebuy count is over 50 | | 200065 | Tournament Summary information is not in English and cannot be parsed | | 200066 | Tournament Summary Information has an invalid, nonparsable format | | 200068 | Unknown database error | | 200069 | Too many missing games reported. You can only report 500 games at a time and have up to 500 missing game requests pending in our database. Please use the SharkScope Desktop to report large numbers of missing games and have them added to the SharkScope database instantly | | 200072 | Player has a reset. Resets must be removed before operation can be performed | | 200073 | Email failed to send | | 200074 | Manual missing game report failed | | 200075 | A result for this player in this tournament is already in the database | | 200076 | A result for a player finishing in this position in this tournament is already in the database | | 200077 | The tournament details provided do not match the details we already have recorded | | 200078 | Player does not exist | | 200079 | The tournament start date must be before the end date | | 200080 | PokerStars players from countries that allow money transfers must use PokerStars money transfer system to opt in and out | | 200081 | Too Many Players Requested | | 200082 | This player is not opted-out, but they have uploaded data in private mode | | 200083 | Unknown time zone. Time zone strings must match valid region-based identifiers from the IANA Time Zone database | | 200084 | The hand history you provided could not be parsed. Please verify the format and try again | | 200085 | Invalid value for parameter: \ | | 200086 | The specified tournament is not a rebuy or re-entry tournament | | 200087 | This network already tracks individual rebuys/re-entries for this tournament; user-reported counts are not accepted | | 200088 | The rebuy/re-entry count for this player and tournament has been recorded by the system and cannot be modified | | 200089 | This player already has a country set | | 200092 | That tag is not valid | | 200093 | You have used all the tags your plan allows | | 200094 | That label name is not valid | | 200095 | You have used all the labels your plan allows | | 200096 | You already have a label with that name | | 200097 | That label no longer exists | | 200098 | That rule is not valid. A rule needs at least one constraint, and cannot be built from a saved search | | 200099 | You have used all the auto-label rules your plan allows | | 200100 | That label is filled in automatically, so it cannot be edited by hand | | 200101 | That player has already been identified, so it can no longer be claimed | | 200102 | We do not yet hold enough information about this player to check a claim against. The network will show us more the next time this account plays | | 200103 | That does not match the details we hold for this player | | 200104 | You have made too many claims recently. Please try again tomorrow | | 200105 | That is not a valid player name | | 200106 | That name is already tracked on this network, so we cannot join the two records automatically. Please contact support and we will do it for you | | 200107 | That is not one of your personal player names. Rebuys and re-entries can only be reported for names you play under yourself | | **System Errors (201xxx)** | | | 201003 | Server is busy. Try again later | | **Filter Errors (202xxx)** | | | 202001 | Filter \ not found | | 202002 | Filter not valid | | 202003 | Load user filters failed | | 202004 | Save failed | | 202005 | Delete failed | | **Filter Constraint Errors (204xxx)** | | | 204001 | Unknown filter constraint "\" | | 204002 | Constraint "\" is not valid for this request | | 204003 | Invalid value(s) for filter constraint "\" | | 204004 | Constraint "\" is not allowed at your user level | | 204005 | Constraint "\" cannot be inverted | | 204006 | Constraint "\" is not valid for this type of search | | **Order Errors (300xxx)** | | | 300001 | Invalid order parameter | | 300002 | Invalid order option | | 300003 | Failed to parse order range | | 300004 | Invalid order range | | 300005 | Order range start must be one or greater | | 300006 | Order range end must be greater than start | | **Notification Errors (301xxx)** | | | 301003 | Invalid Notification Request | | 301004 | Invalid Access | | 301005 | Notification request limit reached | | **Authorization Errors (400xxx)** | | | 400001 | No authorization for this action | | 400002 | Player not opted in | | 400003 | Resets not allowed on this network | | 400004 | Access to this network is not authorized | | 400005 | Access to this application is not authorized | --- ## Appendix ### Best Practices 1. **Authentication** - Store application key securely - Implement proper password hashing - Use headers for auth in production 2. **Rate Limiting** - Respect search quotas - Cache metadata responses - Use `lastUpdateTime` for incremental updates 3. **Filter Optimization** - Use specific constraints to reduce result sets - Leverage saved filters for common queries - Test filters with small date ranges first 4. **Error Handling** - Parse error codes for localization - Implement retry logic for transient errors (201003) - Handle quota exceeded gracefully 5. **Performance** - Use batch operations (completedTournaments bulk) - Leverage caching (3-hour tournament cache) - Paginate large result sets ### Common Use Cases **Get player summary with stats:** ``` GET /api/myapp/networks/pokerstars/players/JohnDoe?filter=Date:1Y ``` **Find tournaments vs specific player:** ``` GET /api/myapp/networks/pokerstars/players/JohnDoe/completedTournaments?order=Best,1~100&filter=VersusPlayer:OpponentName ``` **Get leaderboard rankings:** ``` GET /api/myapp/poker-leaderboards/2025/Scheduled/$16-$35/total ``` **Bulk player results (Commercial):** ``` POST /api/myapp/networks/pokerstars/completedTournaments Content-Type: application/x-www-form-urlencoded players=player1%0Aplayer2%0Aplayer3&filter=Date:7D ``` --- **Document Version:** 1.0.111 **Last Updated:** August 26, 2026 **Copyright © Sharkscope** For support and additional information, visit https://www.sharkscope.com