Reports what happened in a lobby your server created.
Name the matchId your create-lobby endpoint answered, and as idempotencyKey the Idempotency-Key of the create that made it, on every report. On a best-of series lobby, send a progress report after each game session that did not decide the match and a result when a game session does. On a single game session lobby, send one result for it. A result or termination decides the match and moves the tournament on, a progress report records each game session, a status report tells BluMint who is in your lobby and ready, and an abort ends the lobby without a result. Teams are named by any of their players’ in-game ids, as BluMint sent them in the create: one id from a team is enough, and BluMint ignores an id it did not send. Every id is a JSON string, and an id sent as a number is refused with invalid_request. Ignore any field you do not recognise in BluMint’s answers.
On a best-of series, every team in a progress report, result or
abort carries wins, a non-negative integer that counts the starting
wins. On single game sessions, every team in a result carries
placement, from 1, and you send no progress reports. No team carries
both. On a best-of series, count the startingWins the create sent
into every progress, result and abort report. A report with fewer
wins than startingWins answers 400 invalid_wins. placement is an
integer from 1 that ranks every team, and draws are refused. Each
player is an object, { inGameId, stats? }. A result or progress
report may carry free-form stats on the match, each team and each
player, at most 18 levels deep with every key at most 36 UTF-8
bytes, in a request body of at most 208896 bytes (see PartnerStats),
which let BluMint show richer data from your game, such as stats on
a player’s profile, and build deeper integrations with it. Report a
fair-play violation as a termination with reason
fairPlayViolation, and any other forfeit with reason forfeit. BluMint
stores a termination’s reason and note with the report. Timing a
player who doesn’t show up is BluMint’s job, not your game’s, so
abort only when your game itself ends the match without a result.
Which report to send when:
| Situation | Report | Outcome field | retryable | What happens next |
|---|---|---|---|---|
| A game session ended without deciding the match | progress | wins | The match shows the best-of series’ score so far at once. | |
| A best-of series ended, deciding the match | result | wins | BluMint records the result and moves the tournament on. | |
| A single game session ended, deciding the match | result | placement | BluMint records the result and moves the tournament on. | |
| A player forfeited or broke your fair-play rules | termination | The team you name loses the BluMint match, including any game sessions not yet played, whatever the score so far. It is not disqualified from the tournament: the tournament places it as this match’s loser. | ||
| A best-of series ended without a result your game can stand behind (a server failure, a dispute, a client that never came back), and a new lobby could succeed | abort | wins | true | BluMint calls your create-lobby URL again under a new Idempotency-Key, so the players get a new lobby. On a best-of series, startingWins carries the game sessions each team already won. BluMint creates a new lobby for one match, or for one game session on single game sessions, at most two times, counting new lobbies after a host’s reset, and a retryable abort after that hands the match to the host. |
| A best-of series ended without a result your game can stand behind, and a new lobby would end the same way | abort | wins | false | The host takes the match and starts it manually. |
| A single game session ended without a result your game can stand behind (a server failure, a dispute, a client that never came back), and a new lobby could succeed | abort | true | BluMint calls your create-lobby URL again under a new Idempotency-Key, so the players get a new lobby. On a best-of series, startingWins carries the game sessions each team already won. BluMint creates a new lobby for one match, or for one game session on single game sessions, at most two times, counting new lobbies after a host’s reset, and a retryable abort after that hands the match to the host. | |
| A single game session ended without a result your game can stand behind, and a new lobby would end the same way | abort | false | The host takes the match and starts it manually. | |
| A player arrived or became ready for the next game session, a game session started, or a game session ended | status | Nothing a player sees changes. |
When a new lobby could succeed, send the abort with retryable: true, and otherwise with retryable: false. BluMint refuses a report this table does not list with invalid_request.
Status reports are required, on every presence change: each player’s arrival or departure, a player becoming ready for the next game session, and after each game session, when presence resets for the next one. Your 200 to the create counts as the first status report, with every player absent, so send no status report for the create itself, and send your first when a player arrives, at revision 1 or higher. status is pending until the first game session starts and running from then on, so a pending report at a higher revision than a running one answers invalid_request, and one at or below the highest revision answers 200 and changes nothing. Each player is absent (not connected to your lobby), present-not-ready (connected but not ready for the next game session) or present-ready (ready for the next game session or playing it). List every player of the create, absent ones included. If you cannot tell which present player is not ready, report every present player present-not-ready. A player whose client your lobby refused, for example for a version mismatch, is present-not-ready. revision is a positive integer you increase with every status report you send for the match. BluMint keeps the report with the highest revision, so a report at or below the highest it holds answers 200 and changes nothing. BluMint orders reports by revision alone.
How to act on each error code:
| Code | Status | Meaning | What to do |
|---|---|---|---|
invalid_request | 400 | The body breaks the schema, and the message names the first bad field | Fix the report and send it again. |
invalid_placements | 400 | Placements do not rank every team in the match | Fix the report and send it again. |
invalid_wins | 400 | Your wins break a rule of the match’s tally, and the message names each rule you broke. Each team’s wins is a whole number from 0 to gamesToWin; no team is below its startingWins, or below the wins your earlier reports already gave it; a result has exactly one team at gamesToWin, and a progress report or abort has none; every team from the create appears; and an abort names no team twice | Fix the report and send it again. |
roster_mismatch | 400 | The players you named for a team do not belong to exactly one of the teams BluMint sent in this lobby’s create, two of your teams name the same team, or a status report names a player the create never named or names one twice | Check how you map player ids, then send the report again. Resending it unchanged gets the same answer. |
unknown_match | 404 | BluMint has no lobby under this matchId for your API key’s game, and your idempotencyKey names no create BluMint is still recording: your create answer never arrived or BluMint refused it, or the host switched the tournament to another game | Stop without alerting. |
match_not_ready | 503 | The match cannot take results yet, or BluMint is still recording your answer to the create your idempotencyKey names, because you sent the report before your answer reached BluMint. The same report succeeds once BluMint records the answer, whichever players it names | Send the same report again after the Retry-After header’s 30 seconds. |
match_closed | 409 | BluMint no longer takes reports for this matchId: the match is already decided, BluMint moved on to a later game session of it, the host took it over or reset its score, an earlier abort ended this matchId, the match was deleted, or the next match of the tournament already started. It is normal operation, not a fault in your report | Stop without alerting. Resending changes nothing. |
already_scored | 409 | A result for this matchId is already recorded: your own earlier result or termination, for example a retry of a report that already succeeded, or, on single game sessions, a score the host entered by hand for that game session | Stop. The recorded result stands even where it differs from yours. |
A failure on BluMint’s side answers 500. BluMint is alerted, so retry the report.
curl --request POST \
--url https://staging.blumint.io/api/tournaments/match/submit \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"mode": "result",
"matchId": "4f9c2a7e",
"idempotencyKey": "tA1b2-round-1-match-1",
"teams": [
{
"players": [
{
"inGameId": "alice"
}
],
"wins": 3
},
{
"players": [
{
"inGameId": "bob"
}
],
"wins": 1
}
]
}
'{
"stage": "complete"
}{
"code": "invalid_request",
"message": "<string>"
}{
"code": "unknown_match",
"message": "<string>"
}{
"code": "match_closed",
"message": "<string>"
}{
"code": "match_not_ready",
"message": "<string>"
}Authorizations
Body
- result
- progress
- termination
- abort
- status
result 1 - 256The Idempotency-Key of the create that made this match, exactly as BluMint sent it. A report sent before your create answer reaches BluMint finds no match under its matchId yet, and the key tells BluMint which create it is still recording, so it answers 503 match_not_ready rather than 404 unknown_match.
128^[\dA-Za-z-]{1,128}$One entry per team in the match. Every team carries placement on a single game session lobby, or every team carries wins on a best-of series lobby.
1- Option 1
- Option 2
Show child attributes
Show child attributes
Free-form JSON of your choosing. Every number is finite, every key is non-empty, at most 36 UTF-8 bytes and not of the __name__ form, every key and string is well-formed Unicode, with no unpaired UTF-16 surrogate, and nesting stops at 18 levels, the stats object itself being the first. Stats that break any of these answer 400 invalid_request naming the problem. The whole request body is at most 208896 bytes (204 KiB), and a body past it answers 413 before BluMint reads it. Any report inside these bounds is stored whole. BluMint stores them so it can show richer data from your game, such as stats on a player's profile.
Response
The report is recorded. stage is complete for a result or termination, live for a progress report, aborted for an abort, and, for a status report, the status of the highest revision BluMint holds. A progress report for game sessions BluMint already recorded, and a status report at or below the highest revision BluMint holds, write nothing and still answer 200.
complete, live, aborted, pending, running curl --request POST \
--url https://staging.blumint.io/api/tournaments/match/submit \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"mode": "result",
"matchId": "4f9c2a7e",
"idempotencyKey": "tA1b2-round-1-match-1",
"teams": [
{
"players": [
{
"inGameId": "alice"
}
],
"wins": 3
},
{
"players": [
{
"inGameId": "bob"
}
],
"wins": 1
}
]
}
'{
"stage": "complete"
}{
"code": "invalid_request",
"message": "<string>"
}{
"code": "unknown_match",
"message": "<string>"
}{
"code": "match_closed",
"message": "<string>"
}{
"code": "match_not_ready",
"message": "<string>"
}