Seite wählen
Competier API
API docs by Redocly

Competier API (0.8.0)

Download OpenAPI specification:Download

E-mail: competier@alexander-link.de

Competier is a REST HTTPS web service for data processing for competitions of any game and sport. It simplifies organization of tournaments, rankings and games while offering powerful tools for game result processing and rating calculations. Using Competier, you can reach any desired fidelity of service - from offering a simple match history to your players using the Competier App, to feeding a full game replay system by processing all live game data through the Competier API as the action happens, and retrieving it anytime. Cloud-based, flexible, resilient, scalable. Read more on competier.net.

api-key

Required for easy access to all Competier API routes. Your initial API key can be obtained through the Competier App.

Creates and returns a new api key, invalidating the previous one.

Creates and returns a new api key, invalidating the previous one. Your initial API key can be obtained through the Competier App.

Authorizations:
BearerAuth

Responses

ladder

A type of competition in which players are rated based on their performance over an arbitrary timespan, f.e. the chess FIDE rating.

Adds a ladders to an account.

Adds a ladders to an account.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string

The display name for this ladder.

ratingAlgorithm
string

Rating algorithm to use. We support Elo, Glicko-1 and Glicko-2. If you don't have any particular requirements and/or don't know about the details of each algorithm, then we usually recommend Glicko-1.

glickoCValue
number
Default: 18.13
glicko2RValue
number
Default: 0.5
playersCanEnterResults
boolean

Allows players to add and remove results. If allowFullResultHistory is set, players can also add and remove results they haven't themselves participated in.

allowFullResultHistory
boolean

Allows players to see the result history of all other players of this competition, not just their own.

playersCanChangeNames
boolean
allowDuplicateEntryNames
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "My Ladder",
  • "ratingAlgorithm": "Glicko-1",
  • "glickoCValue": 18.13,
  • "glicko2RValue": 0.5,
  • "playersCanEnterResults": false,
  • "allowFullResultHistory": true,
  • "playersCanChangeNames": true,
  • "allowDuplicateEntryNames": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "My Ladder",
  • "ratingAlgorithm": "Glicko-1",
  • "glickoCValue": 18.13,
  • "glicko2RValue": 0.5,
  • "playersCanEnterResults": false,
  • "allowFullResultHistory": true,
  • "playersCanChangeNames": true,
  • "allowDuplicateEntryNames": true
}

Deletes a ladder from an account, including all its entries, ratings and results.

Deletes a ladder from an account, including all its entries, ratings and results.

Authorizations:
BearerAuth
query Parameters
id
required
Array of integers

Id of ladder

Responses

Gets ladders of an account.

Gets ladders of an account. Includes ladders which this account is the admin of, as well as ladders in which this account is participating in as a ladder-entry.

Authorizations:
BearerAuth
query Parameters
adminOnly
Array of booleans

Whether to only return ladders which this account is the admin of.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ladder-entry

Participants of ladders. Represents an instance which competes in the ladder and is rated accordings to its performances. Usually either a single person or a team.

Adds a self-managed entry to a ladder.

Adds a self-managed entry to a ladder. Self-managed entries are not related to actual other Competier accounts - if you want your players to see and interact with your ladder in the Competier App, you need to send them an invite instead.

Authorizations:
BearerAuth
Request Body schema: application/json
required
ladderId
required
integer

id of the ladder that this ladder-entry belongs to.

name
required
string

The display name for this ladder entry.

rating
integer

Allows manually setting rating, for example when moving already existing ladders with ongoing ratings to Competier. Leave as default otherwise.

reliabilityDeviation
integer

For Glicko algorithms: Allows manually setting relaibility deviation, for example when moving already existing ladders with ongoing ratings to Competier. Leave as default otherwise.

Responses

Request samples

Content type
application/json
{
  • "ladderId": 0,
  • "name": "Jane Doe",
  • "rating": 1500,
  • "reliabilityDeviation": 350
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "ladderId": 0,
  • "name": "Jane Doe",
  • "rating": 1500,
  • "reliabilityDeviation": 350,
  • "accountIds": [
    ]
}

Deletes a ladder-entry from a ladder, including all its ratings and results.

Deletes a ladder-entry from a ladder, including all its ratings and results.

Authorizations:
BearerAuth
query Parameters
id
required
Array of integers

Id of ladder-entry

Responses

Gets ladder entries.

Gets ladder entries.

Authorizations:
BearerAuth
query Parameters
ladderId
required
Array of integers

Id of ladder

amount
Array of integers
Example: amount=50

Amount of latest ladder-entries to get. Default and maximum is 50.

offset
Array of integers

Amount of latest ladder-entries to skip. For example, if you have already populated an entry list with 50 ladder-entries, but then your user wants to see more entries, you would fetch those using offset=50.

orderByRating
Array of booleans

By default, entries are ordered by newest added. You can instead specify entries to be ordered by highest rating, resulting in a leaderboard of your ladder.

resultId
Array of integers

Only get entries that participated in the result with this id. This can also be called by non-admins if they themselves participated in the given result, or if the allowFullResultHistory permission is set for its ladder. Mutually exclusive with all other query parameters.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

result

Results of games that have been played. These affect ratings in ladders and standings in tournaments.

Adds a game result for a played game.

Adds a game result for a played game, triggering rating calculation.

It's possible to enter more than two participants, as shown in the example. The Glicko/Elo algorithms don't originally support this - our implementations treat it as 'every entry playing a game against all other entries' and then scale down the total results according to the amount of entries in order to prevent overinflated rating/deviation changes. Due to it being less likely to score your mathematically expected result in a field of, let's say, 20 entries vs. a field of only 2 entries, in practice, rating changes will be slightly less pronounced in larger fields on average. If your type of game/sport/competition lends itself to very large fields, you should consider employing a minimum amount of entries that has to be reached for results to count.

Authorizations:
BearerAuth
Request Body schema: application/json
required
ladderId
integer

Id of the ladder to be referenced. A result must have either a ladderId or a tournamentId.

tournamentId
integer

Currently unused

ladderEntryIds
required
Array of integers

IDs of all ladder-entries that have participated in this game.

finishPositions
required
Array of integers

Describes the game's result for the given ladderEntryIds. In the example case, the ladder entry with the ID 123 has won, 42 has come 2nd, and 13 and 7 share a 3rd place. These results are used for rating calculation.

data
string

Any additional JSON with data you would like to store for this result. This will be returned as is when you GET this result.

Responses

Request samples

Content type
application/json
{
  • "ladderId": 0,
  • "tournamentId": 0,
  • "ladderEntryIds": [
    ],
  • "finishPositions": [
    ],
  • "data": ""
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "ladderId": 0,
  • "tournamentId": 0,
  • "ladderEntryIds": [
    ],
  • "entryNames": [
    ],
  • "finishPositions": [
    ],
  • "oldRatings": [
    ],
  • "ratingChanges": [
    ],
  • "reliabilityDeviationChanges": [
    ],
  • "volatilityChanges": [
    ],
  • "data": ""
}

Deletes a game result by rolling it back, reverting rating changes.

Deletes a game result by rolling it back, reverting rating changes. A result can only be rolled back if it's the most recent result for all of the participating entries.

Authorizations:
BearerAuth
query Parameters
id
required
Array of integers

Id of result

Responses

Gets game results.

Gets game results. By default, results for all ladders that the querying user has participated in are returned.

Authorizations:
BearerAuth
query Parameters
amount
Array of integers
Example: amount=10

Amount of latest game results to get. Default and maximum is 10.

offset
Array of integers

Amount of latest game results to skip. For example, if you have already populated a match history with the 10 latest results, but then your user wants to also see the previous 10 results, you would fetch those using offset=10.

ladderId
Array of integers

Only get your results for the ladder with this id. Mutually exclusive with ladderEntryId.

allLadderEntries
Array of booleans

Get results for all ladder entries of the given ladderId. Only usable by admins or if the allowFullResultHistory permission is set for the ladder. Mutually exclusive with ladderEntryId.

ladderEntryId
Array of integers

Only get results in which the ladderEntry with this id participated. Only usable by admins or if the respective permission has been set for the ladder. Mutually exclusive with ladderId.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

invite

Invites to ladders/tournaments, allowing accounts to partake as ladder-entries in competitions made by other accounts.

Adds an invite.

Adds an invite to a ladder or tournament. Either ladderId or tournamentId needs to be specified.

Authorizations:
BearerAuth
query Parameters
ladderId
Array of integers
Example: ladderId=10

Id of the ladder to create an invite for.

tournamentId
Array of integers

Id of the tournament to create an invite for. Currently unused.

uses
Array of integers

Amount of uses before this invite expires automatically.

teamInvite
Array of integers

Whether this invite should be a "team invite" where all accounts accepting the same invite act as a single ladder-entry in a competition. This is useful if you intend to rate a team constellation as a whole, instead of each player by themselves. Creating a team invite will simultaneously create the preliminary team-ladder-entry, contrary to normal invites which create ladder-entries upon accepting them instead of creating them.

Responses

Response samples

Content type
application/json
{
  • "code": "HHLCdISYcyU=",
  • "ladderId": 0,
  • "tournamentId": 0,
  • "uses": 100,
  • "teamLadderEntryId": 0
}

Accepts an invite.

Accepts an invite, creating a ladder-entry which represents the account calling this route. This action is idempotent since an account can only have one self-representing ladder-entry in a single ladder.

Authorizations:
BearerAuth
query Parameters
code
required
Array of integers
Example: code=10

The code of the invite to accept.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "ladderId": 0,
  • "name": "Jane Doe",
  • "rating": 1500,
  • "reliabilityDeviation": 350,
  • "accountIds": [
    ]
}

Deletes an invite.

Deletes an invite from a ladder or tournament.

Authorizations:
BearerAuth
query Parameters
code
Array of integers
Example: code=10

The code of the invite to delete.

Responses

Gets invites.

Gets all invites for a ladder or tournament.

Authorizations:
BearerAuth
query Parameters
ladderId
Array of integers
Example: ladderId=10

Get all invites for the ladder with this id.

tournamentId
Array of integers

Get all invites for the tournament with this id. Currently unused.

Responses

Response samples

Content type
application/json
[
  • {
    }
]