Admin API Reference
Overview
This API enables administrative actions for developers to manage their Amazon Leaderboards and Tournaments competitions. The API is accessed using an admin api key. The admin API is intended to run from an admin machine; it is not integrated into the game, like the game API.
Note: As our APIs grow and develop, we will continue to add functionality and attributes to our request/response models. To ensure backwards compatibility, we will not remove or change existing attributes. To help prevent breaking your implementation, we encourage that you don't strictly validate schemas and ignore unknown properties.
| Method | Type | Path | Description |
|---|---|---|---|
| Update Game | PUT | /games/{gameId} | Update the game to enable stats-based tournaments. |
| Register Player | POST | /players/register | Register & create a new player token with an identifier that enables players to play across multiple devices. |
| Add Prize List | POST | /prizes | Add a list of in-app prizes for use in tournaments. |
| Get Prize List | GET | /prizes | Get a list of prizes for use in tournaments. |
| Delete Prize | DELETE | /prizes/{prizeId} | Delete an in-app prize. |
| Add Requirement List | POST | /requirements | Add a list of requirements for use against tournaments. |
| Get Requirement List | GET | /requirements | Get a list of requirements for use against tournaments. |
| Create Team | POST | /teams | Create a team for players to join and compete in tournaments with. |
| Add Players to Team | PUT | /teams/{teamId}/players | Add a list of players to a specified team. |
| Remove Players from Team | DELETE | /teams/{teamId}/players | Remove a list of players from a specified team. |
| Add Tournament | POST | /tournaments | Add a tournament for entities like players to join and compete against one another. |
| Add Tournament Series | POST | /tournaments/series | Creates a series of recurring tournaments. |
| Close Tournament | POST | /tournaments/{tournamentId}/close | Manually close a tournament early, determining winners and prizes. |
| Delete Upcoming Tournament | DELETE | /tournaments/{tournamentId} | Deletes a tournament that has not started yet. |
Version information
Version : v1
License information
The API and these materials are Program Materials subject to our Program Materials License Agreement.
URI scheme
- Host :
admin-api.amazongameon.com - Base Path :
/v1 - Schemes :
HTTPS
Paths
Update Game
PUT /games/{gameId}
Description
Update the game to enable stats-based tournaments. Please note that deleting stats is not supported at this time. For subsequent calls to add stats, existing stats are required to be present in the body.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Path | GameId required |
Game Id. This is provided as GameId when you register your game. | string |
| Body | updateGameRequest required |
Information required to update game settings. | UpdateGameRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 204 | Successfully updated the game. | No Content |
| 400 | Invalid request parameters such as missing previously declared stats or having duplicate stats. | No Content |
| 403 | Forbidden. Invalid API Key or Game Id | No Content |
Consumes
application/json
Produces
application/json
Example HTTP request
POST /games/7dd9d75b-8786-4b44-b1fe-a8cd50f0f7e5
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
{
"gameStats":[
"kills", "assists", "gold"
]
}
Example HTTP response
Response 204
Add Prize List
POST /prizes
Description
Add a list of in-app prizes for use in tournaments.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Body | addPrizeListRequest required |
Information required to add a list of in-app prizes. | AddPrizeListRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Successfully added at least one prize. | AddPrizeListResponse |
| 400 | Invalid request parameters. | No Content |
| 401 | Unauthorized. | No Content |
| 403 | Forbidden. Invalid API Key. | No Content |
Consumes
application/json
Produces
application/json
Example HTTP request
Request
POST /prizes
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Request body
{
"prizes": [
{
"description": "This chest contains better loot than the Silver Chest.",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
"title": "Golden Chest",
"prizeInfo": "GOLDEN_CHEST_0124"
},
{
"description": "Live forever with this bundle of health potions.",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
"title": "100 Health Potions",
"prizeInfo": "HEALTH_POTIONS_100"
}
]
}
Example HTTP response
Response 200
{
"addedPrizes": [
{
"description": "This chest contains better loot than the Silver Chest.",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
"prizeId": "caf9a785-d6e8-4990-bf63-49f7d485a8d9",
"title": "Golden Chest",
"prizeInfoType": "VENDOR"
"prizeInfo": "GOLDEN_CHEST_0124"
},
{
"description": "Live forever with this bundle of health potions.",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
"prizeId": "65d738d1-7e81-450e-97c0-79352284145a",
"title": "100 Health Potions",
"prizeInfoType": "VENDOR",
"prizeInfo": "HEALTH_POTIONS_100"
}
]
}
Add Requirement List
POST /requirements
Description
Add a list of requirements for use against tournaments.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Body | requirements required |
List of requirements to add to Amazon Leaderboards and Tournaments. | AddRequirementListRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Successfully added at least one requirement. | AddRequirementListResponse |
| 400 | Invalid request parameters. | No Content |
| 401 | Unauthorized. | No Content |
| 403 | Forbidden. Invalid API Key. | No Content |
Consumes
application/json
Produces
application/json
Example HTTP request
Request
POST /prizes
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Request body
{
"requirements": [
{
"name": "Player is VIP",
"description": "The player has VIP status.",
"type": "value",
"key": "status",
"value": "VIP"
},
{
"name": "Player is a beginner",
"description": "The player has a skill between 0 and 10.",
"type": "range",
"key": "League",
"high": 10,
"low": 0
},
{
"name": "Greater Seattle Area",
"description": "The GPS coordinates of the player is located in the Greater Seattle Area",
"type": "gps",
"key": "gpsCoordinates",
"permittedAreas": [
{
"gpsCoordinates": {
"latitude": 47.60604,
"longitude": -122.3328
},
"radius": 10,
"radiusUnits": "KILOMETERS"
}
]
}
]
}
Example HTTP response
Response 200
{
"addedRequirements": [
{
"name": "Player is VIP",
"description": "The player has VIP status.",
"type": "value",
"key": "status",
"value": "VIP",
"requirementId": "f17abf7f-df0a-4b78-b28a-ddad30f9abf7"
},
{
"name": "Player is a beginner",
"description": "The player has a skill between 0 and 10.",
"type": "range",
"key": "League",
"high": 10,
"low": 0,
"requirementId": "d00d6524-9aaf-4c57-aee3-ec5fe07946ce"
},
{
"name": "Greater Seattle Area",
"description": "The GPS coordinates of the player is located in the Greater Seattle Area",
"type": "gps",
"key": "gpsCoordinates",
"permittedAreas": [
{
"gpsCoordinates": {
"latitude": 47.60604,
"longitude": -122.3328
},
"radius": 10,
"radiusUnits": "KILOMETERS"
}
],
"requirementId": "7ccbfba8-61b8-4abe-a8f1-59d54e324312",
}
]
}
Create Team
POST /teams
Description
Create a team for players to join and compete in tournaments with.
When creating a team you must specify a maximum number of players that are able to join the team. This number will be used to gate access to team competitions that specify a minimum and/or maximum team size requirement – see Add Tournament for more information.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Body | createTeamRequest required |
Request containing information to create a team. | CreateTeamRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Team created successfully. | CreateTeamResponse |
| 400 | Invalid request parameters. | No Content |
| 403 | Forbidden. Invalid API Key. | No Content |
Consumes
application/json
Produces
application/json
Example HTTP request
Request
POST /teams
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Request body
{
"teamName": "Team Name",
"imageUrl": "https://amazon.com/image.png",
"teamSizeMax": 5
}
Example HTTP response
Response 200
{
"teamId": "f9b12bf7-a50e-4cea-b320-e0814cf47616",
"teamName": "Team Name",
"imageUrl": "https://amazon.com/image.png",
"teamSizeMax": 5
}
Add Players to Team
PUT /teams/{teamId}/players
Description
Add a list of players to a specified team.
Teams have a maximum size when created; additional players cannot be added once the maximum size is met. If a player is re-added, they will not consume additional space within the team and will be treated as a no-op.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Path | teamId required |
The ID of the team that players should be added to. | string |
| Body | teamPlayerListRequest required |
A list of player IDs to add to the specified team. | TeamPlayerListRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | All players successfully added to the team. | AddTeamPlayerListResponse |
| 400 | Invalid request parameters. | No Content |
| 403 | Forbidden. Invalid API Key. | No Content |
| 404 | The specified Team ID was not found. | No Content |
| 409 | Unable to add all players due to space constraints. | No Content |
Consumes
application/json
Produces
application/json
Example HTTP request
Request
PUT /teams/f9b12bf7-a50e-4cea-b320-e0814cf47616/players
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Request body
{
"externalPlayerIds": ["9496b5dd-432e-4bef-8297-b6f7b9e1fe29", "b1f2af5b-8bba-480a-831f-0a5f1af94f1c"]
}
Example HTTP response
Response 200
{
"teamSpotsRemaining": 3
}
Remove Players from Team
DELETE /teams/{teamId}/players
Description
Remove a list of players from a specified team.
When a player is removed from a team, they are also removed from any tournaments where they are representing said team if the tournament is in state OPEN or CLOSED where. Upon removal, the team's score will also be deducted/adjusted to reflect the player removal. The player will no longer be eligible for any prizes that may be awarded upon the tournament closing. Tournaments that are completed (tournamentState is COMPLETED) before the player is removed will not be affected. See ()[] for more information on tournament state.
A player cannot be removed if one or more tournaments they are participating are in state WAITING_TO_BE_CLOSED or WAITING_TO_BE_COMPLETED and will result in a partial success. In these cases we encourage you to try to remove the players in a subsequent call.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Path | teamId required |
The ID of the team that players should be added to. | string |
| Body | teamPlayerListRequest required |
A list of player IDs to remove from the specified team. | TeamPlayerListRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | All players successfully removed from the team. | RemoveTeamPlayerListResponse |
| 207 | At least one player unable to be removed from the team. | RemoveTeamPlayerListResponse |
| 400 | Invalid request parameters. | No Content |
| 403 | Forbidden. Invalid API Key. | No Content |
| 404 | The specified Team ID was not found. | No Content |
| 409 | All players specified are not apart of the team and therefore cannot be removed. | No Content |
Consumes
application/json
Produces
application/json
Example HTTP request
Request
DELETE /teams/f9b12bf7-a50e-4cea-b320-e0814cf47616/players
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Request body
{
"externalPlayerIds": ["9496b5dd-432e-4bef-8297-b6f7b9e1fe29", "b1f2af5b-8bba-480a-831f-0a5f1af94f1c"]
}
Example HTTP response
Response 200
{
"teamSpotsRemaining": 5
}
Add Tournament
POST /tournaments
Description
Add a tournament for entities like players to join and compete against one another. A tournament created with this endpoint currently has two different participant types: individual and team.
Individual Tournament
In an individual tournament, players will enter and submit score to compete on an individual bases for a chance to win. When calling the leaderboard for this tournament will display a list of players and their current ranks as they relate to one-another.
Team Tournament
In a team tournament, players will enter (specifying the team they represent) and submit score which contributes to a collective team score for a chance for the entire team to win. If a team wins prize(s), each individual player within the team, at the time the tournament closes, will be provided a copy of that prize that can be claimed. For this reason, please ensure that the prizeInfo for each prize provided can be claimed by multiple players – see AddPrizeListRequest_Prize for more information.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Body | addTournamentRequest required |
Information required to add either an individual or team tournament. | AddIndividualTournamentRequest AddTeamTournamentRequest |
Responses
| HTTP Code | Description | Error Codes | Schema |
|---|---|---|---|
| 200 | Successfully added the tournament. | None | AddTournamentResponse |
| 400 | Invalid request parameters. | [3] | No Content |
| 403 | Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header. | [1] | No Content |
See Error Codes for error code details.
Consumes
application/json
Produces
application/json
Example HTTP request (with participantType INDIVIDUAL)
Request
POST /tournaments
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Request body
{
"countryCodes": [
"US", "CA"
],
"dateEnd": 1515119589135,
"dateStart": 1515105189135,
"description": "Tournament description",
"entryRequirements": [
["99208d38-cac9-45fe-8bfd-954ff7e3ae11"],
["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"]
],
"visibilityRequirements": [
["99208d38-cac9-45fe-8bfd-954ff7e3ae11"],
["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"]
],
"generateAccessKey": true,
"imageUrl": "https://amazon.com/image.png",
"leaderboardStat": "kills",
"matchesMax": 1,
"matchesPerPlayer": 1,
"metadata": "{\"stage\": 5, \"difficulty\": 9}",
"playerAttemptsPerMatch": 100,
"playersPerMatch": 500,
"prizeBundles": [
{
"prizeIds": [
"0031dc56-43e5-440f-9e05-ca747c28150e",
"a6c0bc2a-d04f-449b-aa11-326072610592"
],
"rankFrom": 1,
"rankTo": 3,
"title": "Prize Title",
"description": "Prize Description",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png"
},
{
"prizeIds": [ "a6c0bc2a-d04f-449b-aa11-326072610592" ],
"rankFrom": 4,
"rankTo": 10,
"title": "Prize Title #2",
"description": "Prize Description #2",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-2.png"
}
],
"scoreType": "INDIVIDUAL",
"subtitle": "Tournament Subtitle",
"title": "Tournament Title",
"winType": "HIGHEST",
"releaseType":"MANUAL"
}
Example HTTP response (with participantType INDIVIDUAL)
Response 200
{
"accessKey": "HDLD",
"countryCodes": [
"US", "CA"
],
"dateEnd": 1515119589135,
"dateStart": 1515105189135,
"description": "Tournament description",
"entryRequirements": [
[ "99208d38-cac9-45fe-8bfd-954ff7e3ae11" ],
[ "35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de" ]
],
"visibilityRequirements": [
[ "99208d38-cac9-45fe-8bfd-954ff7e3ae11" ],
[ "35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de" ]
],
"imageUrl": "https://amazon.com/image.png",
"leaderboardStat": "kills",
"matchesMax": 1,
"matchesPerPlayer": 1,
"metadata": "{\"stage\": 5, \"difficulty\": 9}",
"participantType": "INDIVIDUAL",
"playerAttemptsPerMatch": 100,
"playersPerMatch": 500,
"prizeBundles": [
{
"prizeIds": [
"0031dc56-43e5-440f-9e05-ca747c28150e",
"a6c0bc2a-d04f-449b-aa11-326072610592"
],
"rankFrom": 1,
"rankTo": 3,
"title": "Prize Title",
"description": "Prize Description",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png"
},
{
"prizeIds": [ "a6c0bc2a-d04f-449b-aa11-326072610592" ],
"rankFrom": 4,
"rankTo": 10,
"title": "Prize Title #2",
"description": "Prize Description #2",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-2.png"
}
],
"scoreType": "INDIVIDUAL",
"subtitle": "Tournament Subtitle",
"tournamentId": "1fd35e57-ad7a-49b9-8739-c6f64f55ae63",
"title": "Tournament Title",
"winType": "HIGHEST",
"releaseType":"MANUAL"
}
Example HTTP request (for participantType TEAM)
Request
POST /tournaments
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Request body
{
"dateEnd": 1515119589135,
"dateStart": 1515105189135,
"description": "Tournament description",
"entryRequirements": [
["99208d38-cac9-45fe-8bfd-954ff7e3ae11"],
["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"]
],
"visibilityRequirements": [
["99208d38-cac9-45fe-8bfd-954ff7e3ae11"],
["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"]
],
"imageUrl": "https://amazon.com/image.png",
"leaderboardStat": "kills",
"playerAttemptsMax": 100,
"prizeBundles": [
{
"prizeIds": [
"0031dc56-43e5-440f-9e05-ca747c28150e",
"a6c0bc2a-d04f-449b-aa11-326072610592"
],
"rankFrom": 1,
"rankTo": 3,
"title": "Prize Title",
"description": "Prize Description",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png"
},
{
"prizeIds": [ "a6c0bc2a-d04f-449b-aa11-326072610592" ],
"rankFrom": 4,
"rankTo": 10,
"title": "Prize Title #2",
"description": "Prize Description #2",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-2.png"
}
],
"scoreType": "INDIVIDUAL",
"subtitle": "Tournament Subtitle",
"title": "Tournament Title",
"teamSizeMin": 5,
"teamSizeMax": 5
}
Example HTTP response (with participantType TEAM)
Response 200
{
"dateEnd": 1515119589135,
"dateStart": 1515105189135,
"description": "Tournament description",
"entryRequirements": [
[ "99208d38-cac9-45fe-8bfd-954ff7e3ae11" ],
[ "35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de" ]
],
"visibilityRequirements": [
[ "99208d38-cac9-45fe-8bfd-954ff7e3ae11" ],
[ "35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de" ]
],
"imageUrl": "https://amazon.com/image.png",
"leaderboardStat": "kills",
"matchesMax": 1,
"matchesPerPlayer": 1,
"metadata": "{\"stage\": 5, \"difficulty\": 9}",
"participantType": "TEAM",
"playerAttemptsPerMatch": 100,
"playersPerMatch": 1000000000,
"prizeBundles": [
{
"prizeIds": [
"0031dc56-43e5-440f-9e05-ca747c28150e",
"a6c0bc2a-d04f-449b-aa11-326072610592"
],
"rankFrom": 1,
"rankTo": 3,
"title": "Prize Title",
"description": "Prize Description",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png"
},
{
"prizeIds": [ "a6c0bc2a-d04f-449b-aa11-326072610592" ],
"rankFrom": 4,
"rankTo": 10,
"title": "Prize Title #2",
"description": "Prize Description #2",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-2.png"
}
],
"scoreType": "INDIVIDUAL",
"subtitle": "Tournament Subtitle",
"tournamentId": "1fd35e57-ad7a-49b9-8739-c6f64f55ae63",
"title": "Tournament Title",
"winType": "HIGHEST",
"releaseType":"AUTO",
"teamSizeMin": 5,
"teamSizeMax": 5
}
Add Tournament Series
POST /tournaments/series
Description
Create a series of recurring tournaments. Series is currently not supported for team tournaments.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | x-api-key optional |
Admin API key. This is provided when you register your game. | string |
| Body | addTournamentSeriesRequest optional |
JSON representation of AddTournamentSeriesRequest | AddTournamentSeriesRequest |
Responses
| HTTP Code | Description | Error Codes | Schema |
|---|---|---|---|
| 200 | Successfully created the tournament series. | None | AddTournamentSeriesResponse |
| 400 | Invalid request parameters. | [3] | No Content |
| 403 | Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header. | [1] | No Content |
See Error Codes for error code details.
Consumes
application/json
Produces
application/json
Example HTTP request
Request
POST /tournaments/series
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Request body
{
"dateStartList": [
1520370000000,
1520456400000
],
"numOfOccurrences": 2,
"duration": 3600000,
"cadence": 604800000,
"description": "Tournament description",
"leaderboardStat": "kills",
"matchesMax": 1,
"matchesPerPlayer": 1,
"playerAttemptsPerMatch": 1,
"playersPerMatch": 1,
"subtitle": "Tournament Subtitle",
"title": "Tournament Title",
"releaseType": "manual"
}
Example HTTP response
Response 200
{
"seriesId": "f376b33a-345a-4e98-ac00-911687704045",
"tournamentIds": [
"40fdc6e7-347e-4118-bb89-6f6d9f41a331",
"17f93537-00af-4add-9ccf-3978845ce850"
],
"leaderboardStat": "kills",
"firstTournamentStartDate": 1520370000000,
"lastTournamentEndDate": 1520460000000,
"title": "Tournament Title",
"subtitle": "Tournament Subtitle",
"description": "Tournament description",
"winType": "HIGHEST",
"matchesMax": 1,
"playersPerMatch": 1,
"matchesPerPlayer": 1,
"playerAttemptsPerMatch": 1,
"scoreType": "INDIVIDUAL",
"releaseType": "MANUAL"
}
Close Tournament
POST /tournaments/{tournamentId}/close
Description
Manually close a tournament.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Path | tournamentId required |
The identifier of the tournament to close manually. | string |
Responses
| HTTP Code | Description | Error Codes | Schema |
|---|---|---|---|
| 202 | Successfully accepted the request to close the tournament asynchronously. | None | No Content |
| 400 | Invalid request parameters. | [3] | No Content |
| 403 | Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header. | [1] | No Content |
| 404 | The tournament with the provided 'tournamentId' could not be found. | [200] | No Content |
| 409 | Can happen for multiple reasons, please refer to the list of error codes. | [217, 218, 219] | No Content |
See Error Codes for error code details.
Example HTTP request
Request
POST /tournaments/54d8fd8d-e349-49d8-902c-0558365ac22b/close
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Example HTTP response
Response 202 (releaseType = AUTO)
{
"message": "Request received to close tournament 54d8fd8d-e349-49d8-902c-0558365ac22b. Processing tournament to rank players and award prizes (if any)."
}
Response 202 (releaseType = MANUAL)
{
"message": "Request received to close tournament 54d8fd8d-e349-49d8-902c-0558365ac22b. Please wait while we process the tournament to rank players. To complete the tournament and award prizes (if any) call closeTournament again."
}
Delete Upcoming Tournament
DELETE /tournaments/{tournamentId}
Description
Deletes a tournament that has not started yet.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Path | tournamentId required |
The identifier of the tournament to close manually. | string |
Responses
| HTTP Code | Description | Error Codes | Schema |
|---|---|---|---|
| 200 | Successfully deleted the provided 'tournamentId'. | None | No Content |
| 400 | Invalid request parameters. | [3] | No Content |
| 403 | Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header. | [1] | No Content |
| 404 | The tournament with the provided 'tournamentId' could not be found. | [200] | No Content |
| 409 | Cannot perform action on provided 'tournamentId' because it has already started. | [204] | No Content |
See Error Codes for error code details.
Example HTTP request
Request
DELETE /tournament/54d8fd8d-e349-49d8-902c-0558365ac22b
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Get Prize List
GET /prizes
Description
Get the list of available prizes for a game based on its admin API key. Prizes that have expired, or one-time prizes that have already been used, will not be returned.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Successfully added at least one prize. | GetPrizeListResponse |
| 400 | Invalid request parameters. | No Content |
| 403 | Forbidden. Invalid API Key. | No Content |
Produces
application/json
Example HTTP request
Request
GET /prizes
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Example HTTP response
Response 200
{
"prizes": [
{
"description": "Live forever with this bundle of health potions.",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
"prizeId": "65d738d1-7e81-450e-97c0-79352284145a",
"title": "100 Health Potions",
"prizeInfoType": "VENDOR"
},
{
"description": "This chest contains better loot than the Silver Chest.",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
"prizeId": "caf9a785-d6e8-4990-bf63-49f7d485a8d9",
"title": "Golden Chest",
"prizeInfoType": "VENDOR"
}
]
}
Delete Prize
DELETE /prizes/{prizeId}
Description
Delete an in-app prize based on game's admin API key. This operation will make a deleted prize become unavailable for any tournaments created afterwards but will not affect any of the past, on-going and upcoming tournaments that have used this prize.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Path | prizeId required |
The ID of the in-app prize to delete. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Successfully delete prize. | No Content |
| 400 | Invalid request parameters. | No Content |
| 403 | Forbidden. Invalid API Key or prize cannot be deleted | No Content |
| 404 | Invalid prizeId. | No Content |
Example HTTP request
Request
DELETE /prizes/a3a631e1-6ece-4ab6-ae6e-91f157e16232
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Get Requirement List
GET /requirements
Description
Get a list of requirements added for use against tournaments.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Successfully added at least one requirement. | GetRequirementListResponse |
| 400 | Invalid request parameters. | No Content |
| 403 | Forbidden. Invalid API Key. | No Content |
Produces
application/json
Example HTTP request
Request
POST /prizes
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Example HTTP response
Response 200
{
"requirements": [
{
"key": "status",
"name": "Player is VIP",
"requirementId": "f17abf7f-df0a-4b78-b28a-ddad30f9abf7",
"type": "value",
"value": "VIP"
},
{
"description": "The player has a skill between 0 and 10.",
"high": 10,
"key": "League",
"low": 0,
"name": "Player is a beginner",
"requirementId": "d00d6524-9aaf-4c57-aee3-ec5fe07946ce",
"type": "range"
},
{
"name": "Greater Seattle Area",
"description": "The GPS coordinates of the player is located in the Greater Seattle Area",
"type": "gps",
"key": "gpsCoordinates",
"permittedAreas": [
{
"gpsCoordinates": {
"latitude": 47.60604,
"longitude": -122.3328
},
"radius": 10,
"radiusUnits": "KILOMETERS"
}
],
"requirementId": "7ccbfba8-61b8-4abe-a8f1-59d54e324312",
}
]
}
Register Player
POST /players/register
Description
Similar to the Game API, Register Player adds a player (and their device) to Amazon Leaderboards and Tournaments, conducts a key exchange, and returns an encrytedToken. However, with the Admin API version, you can also provide a vendorPlayerId to allow multi device account registration. For more information see Register Player for the Game API.
For the new games that are registered after Aug 14, 2018, the Leaderboards and Tournaments advanced security requires generating longer keys (2048 bits) for the players and use OAEP (a padding mechanism) while encrypting and decrypting. These games should only provide 2048-bit client public key and encrypt it with OAEP using the game public key provided during game registration. Cryptography code samples can be found here.
Games that registered with us before Aug 15, 2018 and opted for advanced security, can continue sending 1024-bit client public key and encrypt it without OAEP.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Header | Content-Type required |
application/json |
string |
| Header | X-Api-Key required |
Admin API key. This is provided when you register your game. | string |
| Body | registerPlayerRequest required |
Information required to register a player. | RegisterPlayerRequest |
Responses
| HTTP Code | Description | Error Codes | Schema |
|---|---|---|---|
| 200 | Successfully registered the player. | None | RegisterPlayerResponse |
| 400 | Invalid request parameters. | [3, 100, 101, 102, 103, 104] | No Content |
| 401 | Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header. | [1] | No Content |
| 403 | Invalid x-api-key. Provide a valid Admin API Key in the x-api-key header. | [1] | No Content |
See Error Codes for error code details.
Consumes
application/json
Produces
application/json
Example HTTP request
Request
POST /players/register
Content-Type: application/json
X-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c
Request body
{
"encryptedPayload" : "Iq6nXfcoDYQEKZEDBhiHefKJLn2Q70iU09DKD7lMsEyFwUguI5w5+WYkM4b0MBfagRFsOltocwsyy0ujzYJ7F3QyRjCIdUc0IP8P6OQmU6fuU43u/AKpNLT4HphCzFOFiQwY4Jf6eIyfaClBiuZkB1apXz1qAhaQd5PdrUQ1JTT2dmEIQZF+lXz1bLpOBDbuKMcOVW55xn7CXC0LcyX6Y58ydZ2bFuNFNchY/mK5ubsbvg+b/8k1cdZDS7dtT9LEwgHUI77ZlmyU+dE/91BlM2nRuqyK8yCv+juA4/MvQ+nSeXtGZROkFZmmX45kh3ngrCQp1dqDVWHA749fFew0pg=="
}
Example HTTP response
Response 200
{
"encryptedPlayerToken" : "gIBkQDL6yDAcMC5eMnDBoC+MypR6fbmf4oTEtzDAh27LOhLeO5tow4gXIQ/0rmzom+IqtXVZxtRUJAhLIoWbEwtHJ4Xze8LVU3rXZ1NyJX26tE6pu9SvE5CARcpDJtRc20EGQ965fxt6PWlkFwvn4BJkHzXQ/pEGONpEDTKuhXM="
}
Definitions
UpdateGameRequest
| Name | Description | Schema |
|---|---|---|
| gameStats required |
A list of stats to add to the game to be used for score submission. Example : [ "kills", "assists", "gold"] |
< string > array |
TeamPlayerListRequest
| Name | Description | Schema |
|---|---|---|
| externalPlayerIds required |
A list of player IDs to add or remove from a team. Example : [ "b1f2af5b-8bba-480a-831f-0a5f1af94f1c" ] |
< string > array |
AddTeamPlayerListResponse
| Name | Description | Schema |
|---|---|---|
| teamSpotsRemaining required |
The number of spots remaining after adding or removing players from a team. Example : 3 |
integer (int32) |
RemoveTeamPlayerListResponse
| Name | Description | Schema |
|---|---|---|
| teamSpotsRemaining required |
The number of spots remaining after adding or removing players from a team. Example : 3 |
integer (int32) |
| failedExternalPlayerIds optional |
The players that were requested, but unable to be removed do to various reasons – see Get Tournament Details for more information. The number of spots remaining after adding or removing players from a team. Example : [ "b1f2af5b-8bba-480a-831f-0a5f1af94f1c" ] |
< string > array |
AddPrizeListRequest
| Name | Description | Schema |
|---|---|---|
| prizes required |
The list of in-app prizes to add to Amazon Leaderboards and Tournaments. | < AddPrizeListRequest_Prize > array |
AddPrizeListRequest_Prize
| Name | Description | Schema |
|---|---|---|
| description required |
The description of the prize. Example : "This chest contains better loot than the Silver Chest." |
string |
| imageUrl optional |
The url for the prize image. Example : "https://amazon.com/image.png" |
string |
| title required |
The title of the prize. Example : "Gold Chest" |
string |
| prizeInfo required |
Information for claiming a prize when awarded. Example : "GOLD_CHEST_0123" |
string |
AddPrizeListResponse
| Name | Description | Schema |
|---|---|---|
| addedPrizes required |
The list of prizes added successfully to Amazon Leaderboards and Tournaments. | < AddPrizeListResponse_Prize > array |
| failedPrizes optional |
The list of prizes that failed to add to Amazon Leaderboards and Tournaments. | < AddPrizeListResponse_Prize > array |
AddPrizeListResponse_Prize
| Name | Description | Schema |
|---|---|---|
| description required |
The description of the prize. Example : "This chest contains better loot than the Silver Chest." |
string |
| imageUrl optional |
The url for the prize image. Example : "https://amazon.com/image.png" |
string |
| prizeId optional |
The prize identifier which may be blank if the prize failed to add. Example : eed51953-530d-4516-92c0-401c0995c21d |
string |
| title required |
The title of the prize. Example : "Gold Chest" |
string |
| prizeInfo required |
Information for claiming a prize when awarded. Example : "GOLD_CHEST_0123" |
string |
| prizeInfoType required |
Describes what is contained in prizeInfo Values : "VENDOR" |
string |
AddRequirementListRequest
| Name | Description | Schema |
|---|---|---|
| requirements required |
The list of requirements to add to Amazon Leaderboards and Tournaments, which can be of multiple type. | < RequirementListType_Value | RequirementListType_Range | RequirementListType_Contains | RequirementListType_GPS | RequirementListType_Regex > array |
RequirementListType_GPS
| Name | Description | Schema |
|---|---|---|
| name required |
The name of the requirement. Example : "Greater Seattle Area" |
string |
| description optional |
The description of the requirement. Example : "The GPS coordinates of the player is located in the Greater Seattle Area" |
string |
| type required |
The type of the requirement. Example : "gps" |
string |
| key required |
The key of the requirement. Example : "gpsCoordinates" |
string |
| permittedAreas required |
The permitted areas of the requirement. | < RequirementList_PermittedArea > array |
RequirementListType_Range
| Name | Description | Schema |
|---|---|---|
| name required |
The name of the requirement. Example : "Player is a beginner" |
string |
| description optional |
The description of the requirement. Example : "The player has a skill between 0 and 10." |
string |
| type required |
The type of the requirement. Example : "range" |
string |
| high required |
The high range (inclusive) of the requirement. Example : 10 |
number (double) |
| key required |
The key of the requirement. Example : "skill" |
string |
| low required |
The low range (inclusive) of the requirement. Example : 0 |
number (double) |
RequirementListType_Regex
| Name | Description | Schema |
|---|---|---|
| name required |
The name of the requirement. Example : "Number Players" |
string |
| description optional |
The description of the requirement. Example : "The player name contains numbers only." |
string |
| type required |
The type of the requirement. Example : "regex" |
string |
| key required |
The key of the requirement. Example : "name" |
string |
| value required |
The value of the requirement. Example : "^[0-9]+$" |
string |
RequirementListType_Value
| Name | Description | Schema |
|---|---|---|
| name required |
The name of the requirement. Example : "Player is VIP" |
string |
| description optional |
The description of the requirement. Example : "The player has VIP status." |
string |
| type required |
The type of the requirement. Example : "value" |
string |
| key required |
The key of the requirement. Example : "status" |
string |
| value required |
The value of the requirement. Example : "VIP" |
string |
RequirementListType_Contains
| Name | Description | Schema |
|---|---|---|
| name required |
The name of the requirement. Example : "Player Origin" |
string |
| description optional |
The description of the requirement. Example : "Country the player resides in." |
string |
| type required |
Contains can match the provided requirement from a list. Example : "contains" |
string |
| key required |
The key of the requirement. Example : "origin" |
string |
| values required |
List of possible values (converted uppercase). Example : ["US", "IN", "FR"] |
string |
AddRequirementListResponse
| Name | Description | Schema |
|---|---|---|
| addedRequirements required |
The list of requirements added successfully to Amazon Leaderboards and Tournaments. | < RequirementListResponse_Requirement > array |
| failedRequirements optional |
The list of requirements that failed to add to Amazon Leaderboards and Tournaments. | < RequirementListResponse_Requirement > array |
AddIndividualTournamentRequest
| Name | Description | Schema |
|---|---|---|
| participantType optional |
The type of participants that will be in the tournament. For an individual tournament use INDIVIDUAL, For a team tournament please see AddTeamTournamentRequest. |
string |
| countryCodes optional |
List of countries players can participate from. Value must be a list of valid ISO 3166-1 Alpha-2 country codes. Example : ["US", "CA"] |
< string > array |
| dateEnd required |
The timestamp for when the tournament should end. Example : 1513943202000 |
integer (int64) |
| dateStart required |
The timestamp for when the tournament should start. Example : 1513899902000 |
integer (int64) |
| description optional |
The description of the tournament. Example : "Compete against the best players and see if you can come out on top!" |
string |
| entryRequirements optional |
Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| visibilityRequirements optional |
Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| generateAccessKey optional |
Flag to determine whether an access key should be generated or not. Example : false |
boolean |
| imageUrl optional |
The url for the tournament image. Example : "https://amazon.com/image.png" |
string |
| leaderboardStat optional |
The stat to use to rank the leaderboard for the tournament. Example : kills |
string |
| matchesMax optional |
The max number of matches for the tournament. Limit is 50. Defaults to 1. Example : 1 |
integer (int16) |
| matchesPerPlayer optional |
The max number of matches a player can join. Defaults to 1. Example : 3 |
integer (int16) |
| metadata optional |
Any metadata to associate with the tournament. Example : "{\"stage\": 5, \"difficulty\": 9}" |
string |
| playerAttemptsPerMatch optional |
The maximum number of player attempts per match. Defaults to 1,000,000,000. Example : 5 |
integer (int32) |
| playersPerMatch optional |
The maximum number of players per match. Defaults to 1,000,000,000. Example : 100 |
integer (int32) |
| prizeBundles optional |
The list of prize bundles to award winning players. | < AddTournament_PrizeBundle > array |
| scoreType optional |
Indicate if the scoring model is INDIVIDUAL or CUMULATIVE. INDIVIDUAL will take the best score submitted, where as CUMULATIVE will sum all submitted scores together. Using CUMULATIVE in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to INDIVIDUAL. Example : "INDIVIDUAL" |
string |
| subtitle optional |
The subtitle of the tournament. Example : "Are you the best of the best?" |
string |
| title required |
The title of the tournament. Example : "Championship Tournament!" |
string |
| winType optional |
Indicate if the LOWEST or HIGHEST score will win. Defaults to HIGHEST. Example : "HIGHEST" |
string |
| releaseType optional |
Indicate if the prizes for this tournament should be released automatically (AUTO) or manually (MANUAL) by the developer. Defaults to AUTO. Example : "AUTO" |
string |
AddTeamTournamentRequest
| Name | Description | Schema |
|---|---|---|
| participantType required |
The type of participants that will be in the tournament. For a team tournament use TEAM, For an individual tournament please see AddIndividualTournamentRequest. |
string |
| countryCodes optional |
List of countries players can participate from. Value must be a list of valid ISO 3166-1 Alpha-2 country codes. Example : ["US", "CA"] |
< string > array |
| dateEnd required |
The timestamp for when the tournament should end. Example : 1513943202000 |
integer (int64) |
| dateStart required |
The timestamp for when the tournament should start. Example : 1513899902000 |
integer (int64) |
| description optional |
The description of the tournament. Example : "Compete against the best players and see if you can come out on top!" |
string |
| entryRequirements optional |
Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| visibilityRequirements optional |
Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Which team a player is in also determines visiblity. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| generateAccessKey optional |
Flag to determine whether an access key should be generated or not. Example : false |
boolean |
| imageUrl optional |
The url for the tournament image. Example : "https://amazon.com/image.png" |
string |
| leaderboardStat optional |
The stat to use to rank the leaderboard for the tournament. Example : kills |
string |
| metadata optional |
Any metadata to associate with the tournament. Example : "{\"stage\": 5, \"difficulty\": 9}" |
string |
| playerAttemptsMax optional |
The maximum attempts for a player to submit a score for their team. Defaults to 1. Example : 5 |
integer (int32) |
| prizeBundles optional |
The list of prize bundles to award winning players. | < AddTournament_PrizeBundle > array |
| teamSizeMin optional |
The minimum team size allowed to enter the tournament. Will only be provided for a team tournament. Example : "3" |
string |
| teamSizeMax optional |
The maximum team size allowed to enter the tournament. Will only be provided for a team tournament. Example : "5" |
string |
| scoreType optional |
Indicate if the scoring model is INDIVIDUAL or CUMULATIVE. INDIVIDUAL will take the best score submitted, where as CUMULATIVE will sum all submitted scores together. Using CUMULATIVE in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to INDIVIDUAL. Example : "INDIVIDUAL" |
string |
| subtitle optional |
The subtitle of the tournament. Example : "Are you the best of the best?" |
string |
| title required |
The title of the tournament. Example : "Championship Tournament!" |
string |
| winType optional |
Indicate if the LOWEST or HIGHEST score will win. Defaults to HIGHEST. Example : "HIGHEST" |
string |
| releaseType optional |
Indicate if the prizes for this tournament should be released automatically (AUTO) or manually (MANUAL) by the developer. Defaults to AUTO. Example : "AUTO" |
string |
AddTournamentResponse
| Name | Description | Schema |
|---|---|---|
| accessKey optional |
Access key value needed to enter the tournament. Example : "BRTC" |
string |
| countryCodes optional |
List of countries players can participate from. The value depends on countryCodes in request. Value will be a list of valid ISO 3166-1 Alpha-2 country codes. Example : ["US", "CA"] |
< string > array |
| dateEnd required |
The timestamp for when the tournament should end. Example : 1513943202000 |
integer (int64) |
| dateStart required |
The timestamp for when the tournament should start. Example : 1513899902000 |
integer (int64) |
| description required |
The title of the tournament. Example : "Compete against the best players and see if you can come out on top!" |
string |
| entryRequirements optional |
Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| visibilityRequirements optional |
Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| imageUrl optional |
The url for the tournament image. Example : "https://amazon.com/image.png" |
string |
| leaderboardStat optional |
The stat to use to rank the leaderboard for the tournament. Example : kills |
string |
| matchesMax required |
The max number of matches for the tournament. Limit is 50. Example : 1 |
integer (int16) |
| matchesPerPlayer required |
The max number of matches a player can join. Example : 3 |
integer (int16) |
| metadata optional |
Any metadata to associate with the tournament. Example : "{\"stage\": 5, \"difficulty\": 9}" |
string |
| participantType required |
The type of participants that will be in the tournament. Example : "INDIVIDUAL" |
string |
| playerAttemptsPerMatch optional |
The maximum number of player attempts per match. Example : 5 |
integer (int32) |
| playersPerMatch required |
The maximum number of players per match. Example : 100 |
integer (int32) |
| prizeBundles required |
The list of prize bundles to award winning players. | < AddTournament_PrizeBundle > array |
| teamSizeMin optional |
The minimum team size allowed to enter the tournament. Will only be provided for a team tournament. Example : "3" |
string |
| teamSizeMax optional |
The maximum team size allowed to enter the tournament. Will only be provided for a team tournament. Example : "5" |
string |
| scoreType optional |
Indicate if the scoring model is INDIVIDUAL or CUMULATIVE. INDIVIDUAL will take the best score submitted, where as CUMULATIVE will sum all submitted scores together. Using CUMULATIVE in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to INDIVIDUAL. Example : "INDIVIDUAL" |
string |
| subtitle optional |
The subtitle of the tournament. Example : "Are you the best of the best?" |
string |
| title required |
The title of the tournament. Example : "Championship Tournament!" |
string |
| tournamentId required |
The id of the tournament. Example : "1fd35e57-ad7a-49b9-8739-c6f64f55ae63" |
string |
| winType optional |
Indicate if the LOWEST or HIGHEST score will win. Example : "HIGHEST" |
string |
| releaseType optional |
Indicate if the prizes for this tournament should be released automatically (AUTO) or manually (MANUAL) by the developer. Example : "AUTO" |
string |
AddTournament_PrizeBundle
| Name | Description | Schema |
|---|---|---|
| description optional |
The description of the tournament. Example : "Top 3 players will win this!" |
string |
| imageUrl optional |
The image url for the prize bundle. Example : "https://amazon.com/image.png" |
string |
| prizeIds required |
List of prize ids awarded in bundle. Example : [be2f5858-5d90-41aa-844b-8862591671ab, 2cbbf9e1-772a-4d01-8ba5-b336c79c8c30] |
< string > array |
| rankFrom required |
The highest rank to award the prizes to (inclusive.) Example : 1 |
integer (int32) |
| rankTo required |
The lowest rank to award the prizes to (inclusive.) Example : 3 |
integer (int32) |
| title required |
The title of the prize bundle. Example : "Gold Chest" |
string |
AddTournamentSeriesRequest
| Name | Description | Schema |
|---|---|---|
| dateStartList required |
List of timestamp to create tournaments startDates. Example : [1513943202000] |
integer (int64) |
| dateEnd optional |
The timestamp for when the series should end. Either dateEnd or numOfOccurrences need to be set. Example : 1513899902000 |
integer (int64) |
| numOfOccurrences optional |
The number of tournament occurrences in the series. Either numOfOccurrences or dateEnd need to be set. Example : 12 |
integer (int64) |
| cadence required |
The tournament series frequency every hour/day/week/month… Example : 86400000 |
integer (int64) |
| duration required |
The tournament duration in milliseconds. Example : 3600000 |
integer (int64) |
| description required |
The description of the tournament. Example : "Compete against the best players and see if you can come out on top!" |
string |
| entryRequirements optional |
Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| visibilityRequirements optional |
Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| generateAccessKey optional |
Flag to determine whether an access key should be generated or not. Example : false |
boolean |
| imageUrl optional |
The url for the tournament image. Example : "https://amazon.com/image.png" |
string |
| leaderboardStat optional |
The stat to use to rank the leaderboard for the tournament. Example : kills |
string |
| matchesMax required |
The max number of matches for the tournament. Limit is 50. Example : 1 |
integer (int16) |
| matchesPerPlayer required |
The max number of matches a player can join. Example : 3 |
integer (int16) |
| metadata optional |
Any metadata to associate with the tournament. Example : "{\"stage\": 5, \"difficulty\": 9}" |
string |
| playerAttemptsPerMatch required |
The maximum number of player attempts per match. Example : 5 |
integer (int32) |
| playersPerMatch required |
The maximum number of players per match. Example : 100 |
integer (int32) |
| prizeBundles optional |
The list of prize bundles to award winning players. | < AddTournament_PrizeBundle > array |
| scoreType optional |
Indicate if the scoring model is INDIVIDUAL or CUMULATIVE. INDIVIDUAL will take the best score submitted, where as CUMULATIVE will sum all submitted scores together. Using CUMULATIVE in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to INDIVIDUAL. Example : "INDIVIDUAL" |
string |
| subtitle optional |
The subtitle of the tournament. Example : "Are you the best of the best?" |
string |
| title required |
The title of the tournament. Example : "Championship Tournament!" |
string |
| winType optional |
Indicate if the LOWEST or HIGHEST score will win. Defaults to HIGHEST. Example : "HIGHEST" |
string |
| releaseType optional |
Indicate if the prizes for this tournament should be released automatically (AUTO) or manually (MANUAL) by the developer. Defaults to AUTO. Example : "AUTO" |
string |
AddTournamentSeriesResponse
| Name | Description | Schema |
|---|---|---|
| seriesId required |
The series id of scheduled tournaments. Example : "8a129f48-6dc6-4b27-9237-6729b1925db1" |
string |
| tournamentIds required |
List of tournaments ids scheduled in a series. Example : ["fe2f5358-5d90-413a-844b-8833391671ab", "ccbbf9e1-242a-4d01-8ba5-j336c79c8c30"] |
< string > array |
| lastTournamentDateEnd required |
The timestamp for when the last tournament in the series should end. Example : 1513943202000 |
integer (int64) |
| firstTournamentDateStart required |
The timestamp for when the first tournament in the series should start. Example : 1513899902000 |
integer (int64) |
| accessKey optional |
Access key value needed to enter the tournament. Example : "BRTC" |
string |
| description required |
The description of the tournament. Example : "Compete against the best players and see if you can come out on top!" |
string |
| entryRequirements optional |
Requirement set used to determine whether a player may enter this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| visibilityRequirements optional |
Requirement set used to determine whether a player may see this tournament in the form of a list of list of requirement ids for the tournament. The inner level list requirement ids are AND together and the outer level list requirement ids are OR together. Example : [ ["99208d38-cac9-45fe-8bfd-954ff7e3ae11"], ["35831019-b1d7-461a-9af9-22aa4abff68f", "8e37e627-25de-42cf-83df-4bae958d33de"] ] |
< < string > array > array |
| imageUrl optional |
The url for the tournament image. Example : "https://amazon.com/image.png" |
string |
| leaderboardStat optional |
The stat to use to rank the leaderboard for the tournament. Example : kills |
string |
| matchesMax required |
The max number of matches for the tournament. Limit is 50. Example : 1 |
integer (int16) |
| matchesPerPlayer required |
The max number of matches a player can join. Example : 3 |
integer (int16) |
| metadata optional |
Any metadata to associate with the tournament. Example : "{\"stage\": 5, \"difficulty\": 9}" |
string |
| playerAttemptsPerMatch optional |
The maximum number of player attempts per match. Example : 5 |
integer (int32) |
| playersPerMatch required |
The maximum number of players per match. Example : 100 |
integer (int32) |
| prizeBundles required |
The list of prize bundles to award winning players. | < AddTournament_PrizeBundle > array |
| scoreType optional |
Indicate if the scoring model is INDIVIDUAL or CUMULATIVE. INDIVIDUAL will take the best score submitted, where as CUMULATIVE will sum all submitted scores together. Using CUMULATIVE in conjunction with positive and negative scores, a player can be brought up or down a leaderboard, supporting use cases for "League Play" determined by wins and loses or "Elo" ratings in games. Defaults to INDIVIDUAL. Example : "INDIVIDUAL" |
string |
| subtitle optional |
The subtitle of the tournament. Example : "Are you the best of the best?" |
string |
| title required |
The title of the tournament. Example : "Championship Tournament!" |
string |
| winType optional |
Indicate if the LOWEST or HIGHEST score will win. Example : "HIGHEST" |
string |
| releaseType optional |
Indicate if the prizes for this tournament should be released automatically (AUTO) or manually (MANUAL) by the developer. Example : "AUTO" |
string |
CreateTeamRequest
| Name | Description | Schema |
|---|---|---|
| teamName optional |
The name of the team. Example : "Team Name" |
string |
| imageUrl optional |
The image url for the team. Example : "https://amazon.com/image.png" |
string |
| teamSizeMax required |
The maximum number of players that can be in the team at any given time. Example : 5 |
integer (int32) |
CreateTeamResponse
| Name | Description | Schema |
|---|---|---|
| teamId required |
The ID of the team. Example : "f9b12bf7-a50e-4cea-b320-e0814cf47616" |
string |
| teamName required |
The name of the team. Example : "Team Name" |
string |
| imageUrl optional |
The image url for the team. Example : "https://amazon.com/image.png" |
string |
| teamSizeMax required |
The maximum number of players that can be in the team at any given time. Example : 5 |
integer (int32) |
GetPrizeListResponse
| Name | Description | Schema |
|---|---|---|
| prizes required |
The list of prizes in Amazon Leaderboards and Tournaments. | < GetPrizeListResponse_Prize > array |
GetPrizeListResponse_Prize
| Name | Description | Schema |
|---|---|---|
| description required |
The description of the prize. Example : "This chest contains better loot than the Silver Chest." |
string |
| imageUrl optional |
The url for the prize image. Example : "https://amazon.com/image.png" |
string |
| prizeId required |
The prize identifier. Example : eed51953-530d-4516-92c0-401c0995c21d |
string |
| title required |
The title of the prize. Example : "Gold Chest" |
string |
| prizeInfoType required |
Describes what is contained in prizeInfo Values : "VENDOR" |
string |
| dateOfExpiration optional |
The date the prize expires and can no longer be used. Example : 1516654800000 |
integer (int64) |
| cost optional |
The cost of the prize per unit, in USD. Example : 99.99 |
number (double) |
| countryCodes optional |
List of countries players can redeem the prize. Value will be a list of valid ISO 3166-1 Alpha-2 country codes. Example : ["US", "CA"] |
< string > array |
| quantity optional |
The quantity of the prize. Example : 10 |
integer (int32) |
GetRequirementListResponse
| Name | Description | Schema |
|---|---|---|
| requirements required |
The list of requirements added to Amazon Leaderboards and Tournaments, which can be of multiple type. | < RequirementListType_Value | RequirementListType_Range | RequirementListType_GPS | RequirementListType_Regex > array |
RegisterPlayerRequest
| Name | Description | Schema |
|---|---|---|
| encryptedPayload optional |
Client public key, created by the device, that is encrypted with OAEP using the game public key provided upon registering your game. It is only required if advanced security is enabled. Example : "Iq6nXfcoDYQEKZED...749fFew0pg==" |
string |
| vendorPlayerId optional |
Identifier that links a player across multiple devices. Example : "hunkdory" |
string |
RegisterPlayerResponse
| Name | Description | Schema |
|---|---|---|
| encryptedPlayerToken optional |
Encrypted player token. Player token is used for authenticating a player device. This will only be returned if advanced security is enabled. Decrypt with OAEP using the private key corresponding to the client public key that was provided in the request. Example : "gIBkQDL6yDAcMC5e...ONpEDTKuhXM=" |
string |
| playerToken optional |
Used for authenticating a player device and will only be returned if advanced security is disabled. Example : "e29ee83d-0d9f-4167-af1f-26e87f45ca74" |
string |
| externalPlayerId required |
The Leaderboards and Tournaments player id for identifying this unique player. Example : "445f49ac-b920-45b5-ae3b-4255cb9f5388" |
string |
RequirementListResponse_Requirement
| Name | Description | Schema |
|---|---|---|
| name required |
The name of the requirement. Example : "Player is VIP" |
string |
| description optional |
The description of the requirement. Example : "The player has VIP status." |
string |
| type required |
The type of the requirement. Example : "[VALUE, RANGE, REGEX, GPS]" |
string |
| key required |
The key of the requirement. Example : "status" |
string |
| value optional |
The value of the requirement if Value or Regex type. Example : "VIP" |
string |
| values optional |
The values of the requirement if contains type. Example : ["US", "IN, "FR"] |
string |
| high optional |
The high range (inclusive) of the requirement if Range type. Example : 10.5 |
number (double) |
| low optional |
The low range (inclusive) of the requirement if Range type. Example : 1 |
number (double) |
| permittedAreas optional |
The permitted areas of the requirement if GPS type. | < RequirementList_PermittedArea > array |
| requirementId optional |
The requirement identifier which may be blank if the requirement failed to add. Example : "d6924d17-ff9f-4e86-9a8f-1bb6b8f4d057" |
string |
RequirementList_PermittedArea
| Name | Description | Schema |
|---|---|---|
| gpsCoordinates required |
The GPS coordinates of the permitted area. | RequirementList_GPSCoordinates |
| radius required |
The radius around the GPS Coordinates that represents the permitted area. Example : 5.0 |
number (double) |
| radiusUnits required |
The unit distance of the radius value. Example : ["KILOMETERS", "MILES"] |
string |
RequirementList_GPSCoordinates
| Name | Description | Schema |
|---|---|---|
| latitude required |
GPS longitude value in decimal degrees. North values are positive, south values are negative. Example : 47.60604 |
number (double) |
| longitude required |
GPS latitude value in decimal degrees. West values are positive, east values are negative. Example : -122.3328 |
number (double) |