Developer Console

Tournament Organizer API Reference

Overview

The Leaderboards and Tournaments Tournament Organizer API enables developers to show a list of tournaments and also enables gamers to participate in the tournaments organized by streamers and broadcasters.

The API methods return HTTP error codes for expected errors and unanticipated errors. The method documentation below indicates the expected errors for each method. For example, getPlayerTournaments returns code 204 when no tournaments are found, and code 401 for an invalid session ID in the request. The API may return other HTTP error codes for unanticipated errors (such as a code 5XX series error). Games must handle all error codes gracefully and provide an appropriate message to the player/customer based on the specific type of error.

Method Type Path Description
Get Player Tournaments GET /player-tournaments Get the list of tournaments created for a game through a streaming platform like Twitch for the desired period, optionally filtered by tournament status.
Get Player Tournament Details GET /player-tournaments/{tournamentId} Get player tournament details to allow players to see more information about the tournament.
Validate Streaming Platform Account Linking Code PUT /players/streaming-platform-account-linking-code Validate the access code generated by a player through streaming platform. The access code must be validated before the player competition.

Version information

Version : v1

License information

License : The API and these materials are Program Materials subject to our Program Materials License Agreement

URI scheme

  • Host: api.amazongameon.com
  • Base Path: /v1
  • Schemes: HTTPS

Paths

Get Player Tournaments

GET /player-tournaments

Description

This method returns a list of player tournaments. Use the query parameters to filter and limit the list of tournaments.

Parameters

Type Name Description Schema Default
Header X-Api-Key
required
Session API key generated during authentication. string  
Header Session-Id
required
Active session ID. string  
Query filterBy
optional
Filter by tournament's status.
upcoming: Tournaments that are scheduled but haven't started yet.
live: Tournaments that are in progress.
enum:
upcoming
live
live
Query limit
optional
Max number of tournaments to return. number 100
Query period
optional
Use along with filterBy.
When you set filterBy=upcoming, this methods returns the list of tournaments that are going to start within the given period from now.
For example: period=week, filterBy=upcoming => gets the list tournaments that are going to start within the next week.
Period is ignored if you set filterBy=live.
enum:
day
week
month
all
all
Query queryBy
optional
Use game to return player tournaments for the game or creator to return only those that were created by the requesting user. enum:
game
creator
game
Query streamingPlatform
optional
The streaming platform through which the tournament was created, such as Twitch. enum:
twitch
 
Query cursor
optional
Cursor for the next page of results. string  

Responses

HTTP Code Description Schema
200 Successfully sent the list of player tournaments matching the given criteria. GetPlayerTournamentListResponse
204 There are no player tournaments that meet the given criteria. No Content
400 Invalid request parameters. No Content
401 Unauthorized. No valid session ID provided. No Content
403 Forbidden. Invalid API key or Player is banned. No Content

Produces

  • application/json

Example HTTP request

Request
GET /player-tournaments?streamingPlatform=twitch&limit=10&filterBy=upcoming&period=week HTTP/1.1
Session-Id: 81f15ed6-82e2-4f99-8d2e-0cadeaeeb1ca
X-Api-Key: 9a8f707f-a09e-4710-8cf2-7cb5a7b0de57

Example HTTP response

Response 200
{
    "tournaments": [
        {
            "tournamentId": "4d18e54b-bfaf-4c4a-bbf0-061671abb7bf",
            "title": "Thor's Hammer",
            "subtitle": "Worthy shall possess the power!",
            "winType": "HIGHEST",
            "dateStart": 1527203364211,
            "dateEnd": 1537203364211,
            "playersPerMatch": 10,
            "playerAttemptsPerMatch": 20,
            "creatorExternalPlayerId": "bfb65358-efdf-410c-a612-642ced9f8698",
            "creatorPlayerName": "TwitchStreamer1",
            "creatorPlayerIconUrl": "http://twitch.tv/TwitchStreamer1.png",
            "hasAccessKey": false,
            "scoreType": "INDIVIDUAL",
            "streamingPlatform": "TWITCH",
            "matchId": "05f3b0be-5c89-442c-af08-6dbd6378175f",
            "playersEntered": 1278
        },
        {
            "tournamentId": "2004b884-d5b3-44f8-9a40-30df330ec0d5",
            "title": "Loki's Sceptre",
            "subtitle": "Born to be a king!",
            "winType": "HIGHEST",
            "dateStart": 1527203364211,
            "dateEnd": 1537203364211,
            "playersPerMatch": 10,
            "playerAttemptsPerMatch": 20,
            "creatorExternalPlayerId": "bfb65358-efdf-410c-a612-642ced9f8698",
            "creatorPlayerName": "TwitchStreamer1",
            "creatorPlayerIconUrl": "http://twitch.tv/TwitchStreamer1.png",
            "hasAccessKey": false,
            "scoreType": "INDIVIDUAL",
            "streamingPlatform": "TWITCH",
            "matchId": "837d818e-e7c6-4258-bd1c-844c08fe0d01",
            "playersEntered": 147
        }
    ],
    "next": "/player-tournaments?streamingPlatform=twitch&limit=10&filterBy=upcoming&period=week&cursor=NDkyZDY5NTMtM2YwYy00OGIyLWE4YjktMTE5ZGM5MmI3NzE1X1BMQVlFUnw3MzExMzNkYy01NmJlLTQ5NmEtOWJiNi04ZDE4ODZhYTkxYWZ8MTU1MzA5MzkzMjc2NA=="
}

Get Player Tournament Details

GET /player-tournaments/{tournamentId}

Description

Get player tournament details to allow players to see more information about the tournament.

Parameters

Type Name Description Schema
Header session-id
required
Active session id. string
Path tournamentId
required
The tournament id to get details of. string

Responses

HTTP Code Description Schema
200 Successfully got the tournament details. GetPlayerTournamentDetailsResponse
400 Invalid request parameters. No Content
401 Unauthorized. No valid session ID provided. No Content
403 Forbidden. Invalid API key or Player is banned. No Content
404 Tournament ID not found. No Content

Produces

  • application/json

Example HTTP request

Request
GET /player-tournaments/00230795-b4bd-40ef-b181-720ee0ec3d80 HTTP/1.1
Session-Id: 81f15ed6-82e2-4f99-8d2e-0cadeaeeb1ca
X-Api-Key: 9a8f707f-a09e-4710-8cf2-7cb5a7b0de57

Example HTTP response

Response 200
{
  "accessKey": "BCDF",
  "creatorPlayerName": TwitchStreamer1,
  "creatorPlayerIconUrl": "http://twitch.tv/TwitchStreamer1.png",
  "creatorExternalPlayerId": "445f49ac-b920-45b5-ae3b-4255cb9f5388",
  "dateEnd": 1506322800000,
  "dateStart": 1505335200000,
  "description": "It's not about hiring the best troops or winning PvP battles, it's about prevailing against all odds.",
  "hasAccessKey": true,
  "playerAttemptsPerMatch": 3,
  "playersPerMatch": 10,
  "scoreType": "Individual",
  "streamingPlatform": "TWITCH",
  "subtitle": "Pirate's Booty",
  "title": "Curio Quest",
  "tournamentId": "00230795-b4bd-40ef-b181-720ee0ec3d80",
  "tournamentState": "OPEN",
  "winType": "highest",
  "matchId": "e7bcece8-9f1b-11e7-abc4-cec278b6b50a",
  "playersEntered": 1000
}

Validate Access code

PUT /players/streaming-platform-account-linking-code

Description

This API will be used to vaidate the access code before joining the tournament. This code is different than the access code of the tournament. This code is used to link playerId with the actual streaming platform where the code was generated.

Parameters

Type Name Description Schema  
Header Content-Type
required
application/json string  
Header X-Api-Key
required
Session API key generated during auth. string  
Header Session-Id
required
Active session ID. string  

Responses

HTTP Code Description Schema
200 Code was validated successfully. No Content
401 Unauthorized. No valid session ID provided. No Content
403 Forbidden. No valid API Key provided. No Content
409 Invalid Code. No Content

Produces

  • application/json

Example HTTP request

Request
PUT /players/streaming-platform-account-linking-code HTTP/1.1
Session-Id: 81f15ed6-82e2-4f99-8d2e-0cadeaeeb1ca
X-Api-Key: 9a8f707f-a09e-4710-8cf2-7cb5a7b0de57
Request body
{
  "code" : "ABCDE"
}

Example HTTP response

Response 200

Definitions

GetPlayerTournamentListResponse

Name Description Schema
tournaments
optional
List of player tournaments. < GetPlayerTournamentListResponse_Tournament > array
next
optional
URL to retrieve the next page of results. You can use it as-is to make the request for the next page. Absence of this indicates there are no further results. string

GetPlayerTournamentListResponse_Tournament

Name Description Schema
accessKey
optional
Access key to enter the player tournament.
Example : "ABCD"
string
creatorExternalPlayerId
optional
The Duels player id for identifying this unique player.
Example : "11230795-b4bd-40ef-b181-720ee0ec3d80"
string
creatorPlayerName
required
PlayerName of whom created the player tournament.
Example : "TwitchStreamer1"
string
creatorPlayerIconUrl
optional
PlayerIconUrl of whom created the player tournament.
Example : "http://twitch.tv/TwitchStreamer1.png"
string
dateEnd
required
Date tournament ends.
Example : 1506322800000
integer (int64)
dateStart
required
Date tournament starts.
Example : 1505335200000
integer (int64)
hasAccessKey
required
Value to decide if tournament requires access key to enter the tournament or not.
Example : true
boolean
matchId
optional
The matchId of the tournament.
Example : "e7bcece8-9f1b-11e7-abc4-cec278b6b50a"
string
metadata
optional
Additional information that may be needed for tournament.
Example : "My v1 tournament"
string
playerAttemptsPerMatch
required
Maximum number of attempts allowed per player per match.
Example : 3
integer (int32)
playersEntered
optional
The number of players who have entered the tournament.
Example : 1000
integer (int32)
playersPerMatch
required
Maximum number of players allowed to participate in a match.
Example : 1000
integer (int32)
scoreType
required
Whether to save individual scores or accumulate the score submissions.
Example : "individual"
string
streamingPlatform
optional
The streaming platform of the tournament.
Example : "twitch"
string
subtitle
optional
Tournament subtitle.
Example : "Pirate's Booty"
string
title
required
Tournament title.
Example : "Curio Quest"
string
tournamentId
required
Tournament ID.
Example : "00230795-b4bd-40ef-b181-720ee0ec3d80"
string
winType
required
Indicate whether Highest/Lowest score is the winning score.
Example : "highest"
string

GetPlayerTournamentDetailsResponse

Name Description Schema
accessKey
optional
Access key to enter the player tournament.
Example : "BCDF"
string
creatorPlayerName
required
PlayerName of whom created the player tournament.
Example : TwitchStreamer1
string
creatorPlayerIconUrl
optional
PlayerIconUrl of whom created the player tournament.
Example : "http://twitch.tv/TwitchStreamer1.png"
string
creatorExternalPlayerId
optional
Leaderboards and Tournaments playerId of whom created the player tournament.
Example : "445f49ac-b920-45b5-ae3b-4255cb9f5388"
string
dateEnd
required
Date tournament ends.
Example : 1506322800000
integer (int64)
dateStart
required
Date tournament starts.
Example : 1505335200000
integer (int64)
description
optional
Description for tournament.
Example : "It's not about hiring the best troops or winning PvP battles, it's about prevailing against all odds."
string
hasAccessKey
required
Value to decide if tournament requires access key to enter the tournament or not.
Example : false
boolean
playerAttemptsPerMatch
required
Maximum number of attempts allowed per player per match.
Example : 3
integer (int32)
playersPerMatch
required
Maximum number of players allowed to participate in a match.
Example : 10
integer (int32)
scoreType
required
Whether to save individual scores or accumulate the score submissions.
Example : "individual"
string
streamingPlatform
optional
The streaming platform of the tournament.
Example : "twitch"
string
subtitle
optional
Tournament subtitle.
Example : "Pirate's Booty"
string
title
required
Tournament title.
Example : "Curio Quest"
string
tournamentId
required
Tournament ID.
Example : "00230795-b4bd-40ef-b181-720ee0ec3d80"
string
tournamentState
required
The current state of the tournament.
Values :
OPEN: Tournament is upcoming or on-going.
WAITING_TO_BE_CLOSED: Tournament is in the process of closing.
CLOSED: Tournament has closed and is awaiting manual approval in Developer Console.
WAITING_TO_BE_COMPLETED: Tournament is in the process of completing.
COMPLETED: Tournament has finalized and prizes have been awarded.
string
winType
required
Indicate whether Highest/Lowest score is considered best score.
Example : "highest"
string
matchId
optional
Match ID.
Example : "e7bcece8-9f1b-11e7-abc4-cec278b6b50a"
string
playersEntered
optional
The number of player who have entered the tournament.
Example : "1000"
integer (int32)