Developer Console
Sign In
Sign In
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)