Moving from API v1
Where each v1 field is in API v2, and what to change.
Coming soon
Every v1 creator read has its v2 read. Per input, field and behaviour: where v2 answers it, and what an integration changes. A v1 field v2 does not send says why.
GET /api/leaderboard/{code} is GET /api/v2/leaderboards/{code} (leaderboard_get).
| v1 | v2 | What changes |
|---|---|---|
| path code | {code} | Nothing - any code of the creator resolves to their board |
| header x-apikey | - | A key is optional: the board is public. A key sent must be the code owner's v2 key |
| leaderboards | periods | Read periods |
| user | creator | Read creator (v1 sent null here) |
| error | - | An inactive board is a 404 with error.code leaderboard_inactive |
| viewerOnCode | - | The site page's own field, for a signed-in viewer: never sent to a key |
| leaderboards[].id | - | Not sent: an internal number, not a name to keep - the board is named by its code |
| leaderboards[].periodId | periods[].periodId | Nothing |
| leaderboards[].active | periods[].status | active is status === "live" |
| leaderboards[].affiliate.id | - | Not sent: an internal number, not a name to keep - the board is named by its code |
| leaderboards[].affiliate.code | code | Read code, once for the board |
| leaderboards[].dateStart | periods[].startsAt | Read startsAt |
| leaderboards[].dateEnd | periods[].endsAt | Read endsAt |
| leaderboards[].days | periods[].endsAt | floor((endsAt - startsAt) / 86400000) |
| leaderboards[].paid | periods[].paid | Nothing |
| leaderboards[].prizes | periods[].prizes | Nothing |
| leaderboards[].users | periods[].standings | Read standings - send limit=100 for the whole list (the default is 10) |
| leaderboards[].entryUser | - | v1 never sent it to a key: nothing to change |
| leaderboards[].entryPlace | - | v1 never sent it to a key: nothing to change |
| leaderboards[].user.uuid | ?include creator.uuid | creator.uuid with include=uuid |
| leaderboards[].user.name | creator.name | creator.name |
| leaderboards[].user.socials[].type | creator.socials[].type | creator.socials |
| leaderboards[].user.socials[].url | creator.socials[].url | creator.socials |
| leaderboards[].users[].uuid | ?include periods[].standings[].uuid | Add include=uuid - null for a hidden player |
| leaderboards[].users[].rank | periods[].standings[].vipRank | Read vipRank (the VIP tier). The position in the period is place |
| leaderboards[].users[].name | periods[].standings[].name | Nothing |
| leaderboards[].users[].avatar_selected | periods[].standings[].avatar | Read avatar |
| leaderboards[].users[].level | periods[].standings[].level | Nothing |
| leaderboards[].users[].wagered | periods[].standings[].wagered | Nothing |
| leaderboards[].users[].prize | periods[].standings[].prize | Nothing |
| leaderboards[].users[].exchanged | ?include periods[].standings[].exchanged | Add include=exchanged - v1 sent cents, v2 answers coins (v1 / 100) |
| leaderboards[].users[].xpBonus | ?include periods[].standings[].xpBonus | Add include=xpBonus - v1 sent cents, v2 answers coins (v1 / 100) |
| leaderboards[].users[].hidden | - | Not sent: a hidden player reads as Anonymous#### with a null avatar, and with include=uuid a null uuid |
| leaderboards[].users[].roles | - | Not sent: v1 only ever listed the site's streamer badge here, and v2 sends no badges |
| Standings per period: all v1 ranks (the top 100, or every place of a longer prize ladder) | ?limit | Send limit=100 (up to 1000 for a longer ladder) - the default is 10 |
| Periods: the live ones, then the latest ended ones | periods | Nothing |
| Refusals: v1 answered 200 with an error text, or 400 | - | v2 answers {"error": {"code", "message"}}: 404 not_found / leaderboard_inactive, 401 for a wrong key |
| Cache: the standings computed at most every 10 seconds | - | The same standings, and the answer is cached for 5 seconds on top (Cache-Control: public, max-age=5, stale-while-revalidate=25) |
| Rate limit: 60 a minute per IP | - | Nothing: 60 a minute per IP |
| CORS: the site's origins | - | Any origin may now read the board, without credentials |
GET /api/leaderboard/{code}/raffle is GET /api/v2/leaderboards/{code}/raffles (leaderboard_raffles).
| v1 | v2 | What changes |
|---|---|---|
| path code | {code} | Nothing |
| header x-apikey | - | Send your API v2 key (cgw2_...) in x-apikey: one key reads every code you own. A v1 key is refused (401 legacy_key) |
| query take | ?limit | Send limit (1 to 20, default 3), as take |
| raffles | raffles | Nothing |
| error | - | A code with no board is a 404 with error.code not_found |
| raffles[].id | - | Not sent: an internal number, not a name to keep - the board is named by its code |
| raffles[].periodId | raffles[].periodId | Nothing |
| raffles[].active | raffles[].status | v1 always sent false: status says live or ended |
| raffles[].affiliate.id | - | Not sent: an internal number, not a name to keep - the board is named by its code |
| raffles[].affiliate.code | {code} | Not repeated per raffle: it is the code in your request |
| raffles[].dateStart | raffles[].startsAt | Read startsAt |
| raffles[].dateEnd | raffles[].endsAt | Read endsAt |
| raffles[].days | raffles[].endsAt | floor((endsAt - startsAt) / 86400000) |
| raffles[].paid | raffles[].paid | Nothing |
| raffles[].prizes | raffles[].prizes | v1 sent cents, v2 answers coins (v1 / 100) |
| raffles[].users | raffles[].entries | Read entries |
| raffles[].users[].tickets.count | raffles[].entries[].tickets.count | Nothing |
| raffles[].users[].tickets.start | raffles[].entries[].tickets.start | Nothing |
| raffles[].users[].tickets.end | raffles[].entries[].tickets.end | Nothing |
| raffles[].users[].xpLeft | ?include raffles[].entries[].xpLeft | Add include=xpLeft - v1 sent cents, v2 answers coins (v1 / 100) |
| raffles[].user.uuid | ?include creator.uuid (leaderboard_get) | Not repeated per raffle: the creator is your key's own account. GET /api/v2/leaderboards/{code} answers creator.uuid with include=uuid |
| raffles[].user.name | creator.name (leaderboard_get) | Not repeated per raffle: the creator is your key's own account. GET /api/v2/leaderboards/{code} answers creator.name |
| raffles[].user.socials[].type | creator.socials[].type (leaderboard_get) | Not repeated per raffle: the creator is your key's own account. GET /api/v2/leaderboards/{code} answers creator.socials |
| raffles[].user.socials[].url | creator.socials[].url (leaderboard_get) | Not repeated per raffle: the creator is your key's own account. GET /api/v2/leaderboards/{code} answers creator.socials |
| raffles[].users[].uuid | ?include raffles[].entries[].uuid | Add include=uuid - null for a hidden player |
| raffles[].users[].rank | raffles[].entries[].vipRank | Read vipRank (the VIP tier). The position in the period is place |
| raffles[].users[].name | raffles[].entries[].name | Nothing |
| raffles[].users[].avatar_selected | raffles[].entries[].avatar | Read avatar |
| raffles[].users[].level | raffles[].entries[].level | Nothing |
| raffles[].users[].wagered | raffles[].entries[].wagered | v1 sent cents, v2 answers coins (v1 / 100) |
| raffles[].users[].prize | raffles[].entries[].prize | v1 sent cents, v2 answers coins (v1 / 100) |
| raffles[].users[].exchanged | ?include raffles[].entries[].exchanged | Add include=exchanged - v1 sent cents, v2 answers coins (v1 / 100) |
| raffles[].users[].xpBonus | ?include raffles[].entries[].xpBonus | Add include=xpBonus - v1 sent cents, v2 answers coins (v1 / 100) |
| raffles[].users[].hidden | - | Not sent: a hidden player reads as Anonymous#### with a null avatar, and with include=uuid a null uuid |
| raffles[].users[].roles | - | Not sent: v1 only ever listed the site's streamer badge here, and v2 sends no badges |
| A signed-in owner's own raffles without a key | - | The site page's own mode: v2 reads a key, never a cookie |
| Refusals: v1 answered 400 with an error text | - | v2 answers {"error": {"code", "message"}}: 401 missing_key / invalid_key, 404 not_found |
| Rate limit: 60 a minute per IP | - | And 60 a minute per account across its keyed reads |
GET /api/affiliate/external is GET /api/v2/affiliates/{code}/referrals (affiliate_referrals).
| v1 | v2 | What changes |
|---|---|---|
| header x-apikey | - | Send your API v2 key (cgw2_...) in x-apikey: one key reads every code you own. A v1 key is refused (401 legacy_key). No opt-in per code is needed |
| query code | {code} | The code is in the path: /api/v2/affiliates/{code}/referrals |
| query gt | ?from | Send from as an ISO 8601 time, not milliseconds |
| query lt | ?to | Send to as an ISO 8601 time - alone it starts at the beginning, as lt |
| query take | ?limit | Send limit=50000 for the whole table (the default is 50). For the count alone (take=0), send limit=1 and read total |
| query skip | ?cursor | Rows N..M (counting from 1): send limit=M (a bulk read when M is over 100) and keep rows N..M, or page from the first page with cursor |
| query search | ?search | Nothing (at most 64 characters) |
| query sort | ?order | Send order (asc or desc) |
| query by | ?sort | Send sort: createdAt is joinedAt, wager is wagered, deposited and name as they were |
| query currency | ?currency | Nothing |
| success | - | A 200 is a success: v2 answers errors with their status |
| data | referrals | Read referrals |
| count | total | Read total |
| take | ?limit | The limit sent |
| currency | currency | Nothing |
| error | - | v2 answers {"error": {"code", "message"}} with the status |
| data[].id | - | Not sent: an internal number that could change between reads - uuid names the referral |
| data[].uuid | referrals[].uuid | For a hidden referral, an id stable for this code that is not the account's (v1 sends the account id). Every other referral's uuid is the same |
| data[].name | referrals[].name | v1 left the field out for a nameless account, v2 sends "" |
| data[].avatar_selected | referrals[].avatar | Read avatar: null where v1 left the field out |
| data[].level | referrals[].level | Nothing |
| data[].createdAt | referrals[].joinedAt | Read joinedAt |
| data[].status | - | v1 always sent "active": the referral is listed |
| data[].active | referrals[].active | Nothing |
| data[].wagered | referrals[].wagered | Nothing |
| data[].deposited | referrals[].deposited | Nothing |
| data[].commission | referrals[].commission | Nothing |
| A window of any length | ?from | Over 366 days it is a bulk read |
| Rate limit: one call a minute per key, up to 50,000 rows | ?limit | A bulk read (limit over 100, or a window over 366 days) once a minute per account - pages of 100 at 60 a minute |
| The same figures for the same window | - | Nothing: v1 and v2 answer the same figures |
| A code whose figures are still being prepared | - | v1 answered at once. v2 answers 409 stats_not_ready while they are prepared (minutes): try again. Switching to v2 and each new key start preparing every code you own |
If you do not switch
Previous Page
A creator's leaderboard, ready for an overlay GET
The live periods and the latest ended ones with their standings, the newest raffle state, and the embed page. The same answer for every caller, so a browser on any origin may poll it without a key (no cookie is read). A code that is not the board owner's main code resolves to the owner's board. Poll it every few seconds: it is cached for 5 seconds and secondsLeft is counted from serverTime. include adds the account ids (each player and the creator), exchanged and xpBonus to the rows. Rate limits: 60 reads a minute per IP across /api/v2 and at most 25 to one path in 2 seconds (429 with Retry-After).