> ## Documentation Index > Fetch the complete documentation index at: https://docs-staging.blumint.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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. 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 identified 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. Every id and note is well-formed Unicode, with no unpaired UTF-16 surrogate, and each length bound counts characters. Ignore any field you do not recognize 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 identify 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. startingWins carries the game sessions each team already won. BluMint creates a new lobby for one match 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. BluMint creates a new lobby for one game session 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 identifies no team twice | Fix the report and send it again. | | `roster_mismatch` | `400` | The players you identified for a team do not belong to exactly one of the teams BluMint sent in this lobby's create, two of your teams identify the same team, or a status report identifies a player the create never identified or identifies 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` identifies 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` identifies, because you sent the report before your answer reached BluMint. The same report succeeds once BluMint records the answer, whichever players it identifies | 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. ## OpenAPI ````yaml /openapi.json post /tournaments/match/submit openapi: 3.0.1 info: title: BluMint game partner API version: 2.0.0 description: >- Reference for the endpoints your game uses to run BluMint tournaments. For the walkthrough, see the [game integration guide](https://docs.blumint.com). To request an API key, fill in the [game partner setup form](https://staging.blumint.io/contact/game-partner), and for a question, [contact BluMint](https://staging.blumint.io/contact). license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - description: Staging, for building and testing url: https://staging.blumint.io/api - description: Production url: https://app.blumint.com/api security: - ApiKeyAuth: [] tags: [] paths: /tournaments/match/submit: post: tags: - Tournaments summary: Reports what happened in a lobby your server created. description: >- Name the matchId your create-lobby endpoint answered, and as idempotencyKey the Idempotency-Key of the create that made it, on every report. 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. 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 identified 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. Every id and note is well-formed Unicode, with no unpaired UTF-16 surrogate, and each length bound counts characters. Ignore any field you do not recognize 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 identify 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. startingWins carries the game sessions each team already won. BluMint creates a new lobby for one match 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. BluMint creates a new lobby for one game session 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 identifies no team twice | Fix the report and send it again. | | `roster_mismatch` | `400` | The players you identified for a team do not belong to exactly one of the teams BluMint sent in this lobby's create, two of your teams identify the same team, or a status report identifies a player the create never identified or identifies 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` identifies 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` identifies, because you sent the report before your answer reached BluMint. The same report succeeds once BluMint records the answer, whichever players it identifies | 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. operationId: submitMatchResult requestBody: required: true content: application/json: schema: oneOf: - type: object title: result required: - mode - matchId - idempotencyKey - teams properties: mode: type: string enum: - result matchId: $ref: '#/components/schemas/PartnerReportMatchId' idempotencyKey: $ref: '#/components/schemas/PartnerCreateIdempotencyKey' teams: type: array minItems: 1 description: >- 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. items: type: object required: - players oneOf: - required: - placement - required: - wins properties: players: $ref: '#/components/schemas/PartnerReportPlayers' placement: type: integer minimum: 1 description: 1 for the best. Each team is placed exactly once. wins: type: integer minimum: 0 description: >- The game sessions this team won in the match, counting its starting wins. Exactly one team's wins equals gamesToWin. stats: $ref: '#/components/schemas/PartnerStats' stats: $ref: '#/components/schemas/PartnerStats' - type: object title: progress required: - mode - matchId - idempotencyKey - teams properties: mode: type: string enum: - progress matchId: $ref: '#/components/schemas/PartnerReportMatchId' idempotencyKey: $ref: '#/components/schemas/PartnerCreateIdempotencyKey' teams: type: array minItems: 1 description: >- One entry per team in the match, sent after each game session that did not decide the match. Each team's wins is the match's running total after this game session, counting startingWins, never this game session's outcome alone. A drawn or voided game session changes no tally, so it sends nothing. items: type: object required: - players - wins properties: players: $ref: '#/components/schemas/PartnerReportPlayers' wins: type: integer minimum: 0 description: >- The team's total game sessions won in this match so far, including its startingWins. Every team is below gamesToWin. stats: $ref: '#/components/schemas/PartnerStats' stats: $ref: '#/components/schemas/PartnerStats' - type: object title: termination required: - mode - matchId - idempotencyKey - team - reason properties: mode: type: string enum: - termination matchId: $ref: '#/components/schemas/PartnerReportMatchId' idempotencyKey: $ref: '#/components/schemas/PartnerCreateIdempotencyKey' team: type: object description: >- The team whose run in this match ends. It loses the BluMint match, including any game sessions not yet played, whatever the score so far. required: - players properties: players: $ref: '#/components/schemas/PartnerRosterPlayers' reason: type: string enum: - forfeit - fairPlayViolation description: >- fairPlayViolation when the team broke your fair-play rules, forfeit otherwise. Both have the same effect, the one the termination row of "Which report to send when" states. note: type: string minLength: 1 maxLength: 256 description: >- Optional text on what happened, which BluMint stores with the report. - type: object title: abort required: - mode - matchId - idempotencyKey - reason - retryable properties: mode: type: string enum: - abort matchId: $ref: '#/components/schemas/PartnerReportMatchId' idempotencyKey: $ref: '#/components/schemas/PartnerCreateIdempotencyKey' reason: type: string enum: - serverFailure - insufficientPlayers - disputed description: >- Why your game ended the match without a result it can stand behind: your server failed, too few players stayed connected for it to go on, or the result is disputed. BluMint stores it, but only retryable decides what happens next. retryable: type: boolean description: >- Whether a new lobby can succeed. BluMint closes this matchId either way, so a later report for it answers match_closed. teams: type: array minItems: 1 description: >- Each team's running wins, counting its starting wins. Required on an abort of a best-of series lobby, and refused on an abort of a single game session lobby. items: type: object required: - players - wins properties: players: $ref: '#/components/schemas/PartnerRosterPlayers' wins: type: integer minimum: 0 - type: object title: status required: - mode - matchId - idempotencyKey - status - revision - players properties: mode: type: string enum: - status matchId: $ref: '#/components/schemas/PartnerReportMatchId' idempotencyKey: $ref: '#/components/schemas/PartnerCreateIdempotencyKey' status: type: string enum: - pending - running description: >- pending until the first game session starts, running from then on, between game sessions included. 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. revision: type: integer minimum: 1 description: >- A positive integer you increase with every status report you send for this matchId. BluMint keeps the report with the highest revision. players: type: array minItems: 1 description: >- Every player of the create, each once, absent ones included. A player the create never seated answers 400 roster_mismatch. items: type: object required: - inGameId - status properties: inGameId: type: string minLength: 1 maxLength: 256 status: type: string enum: - absent - present-not-ready - present-ready examples: result: summary: A decided best-of series value: mode: result matchId: 4f9c2a7e idempotencyKey: tA1b2-round-1-match-1 teams: - players: - inGameId: alice wins: 3 - players: - inGameId: bob wins: 1 progress: summary: A first-to-3 match after its third game session, at 2 to 1 value: mode: progress matchId: 4f9c2a7e idempotencyKey: tA1b2-round-1-match-1 teams: - players: - inGameId: alice stats: character: Ryu wins: 2 - players: - inGameId: bob stats: character: Ken wins: 1 stats: rounds: 3 termination: summary: A player forfeited value: mode: termination matchId: 4f9c2a7e idempotencyKey: tA1b2-round-1-match-1 team: players: - inGameId: bob reason: forfeit note: Conceded the match from the in-game menu. abort: summary: The game server failed partway through the match value: mode: abort matchId: 4f9c2a7e idempotencyKey: tA1b2-round-1-match-1 reason: serverFailure retryable: true teams: - players: - inGameId: alice wins: 2 - players: - inGameId: bob wins: 1 status: summary: A game session is running value: mode: status matchId: 4f9c2a7e idempotencyKey: tA1b2-round-1-match-1 status: running revision: 3 players: - inGameId: alice status: present-ready - inGameId: bob status: present-ready responses: '200': description: >- 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. content: application/json: schema: type: object required: - stage properties: stage: type: string enum: - complete - live - aborted - pending - running '400': description: >- invalid_request, invalid_placements, invalid_wins or roster_mismatch. content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - invalid_request - invalid_placements - invalid_wins - roster_mismatch message: type: string '401': description: >- The X-Api-Key header is missing or unknown. The body is `{ message }`. '403': description: The API key is not bound to a game. The body is `{ message }`. '404': description: >- unknown_match. No lobby with this matchId was created for your game, and your idempotencyKey identifies no create BluMint is still recording. content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - unknown_match message: type: string '405': description: The method is not POST. The body is `{ message }`. '409': description: match_closed or already_scored. content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - match_closed - already_scored message: type: string '413': description: >- The request body is over 208896 bytes (204 KiB). The body is plain text, not JSON, and BluMint records nothing, so send a smaller report. '500': description: >- A failure on BluMint's side. BluMint is alerted, so retry the report. '503': description: >- match_not_ready. The BluMint match cannot take results yet, or BluMint is still recording your answer to the create your idempotencyKey identifies, so retry later. headers: Retry-After: description: The seconds to wait before retrying, always 30. schema: type: integer example: 30 content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - match_not_ready message: type: string security: - ApiKeyAuth: [] components: schemas: PartnerReportMatchId: type: string minLength: 1 maxLength: 256 description: >- The matchId your create-lobby endpoint answered for this lobby, exactly as you sent it. PartnerCreateIdempotencyKey: type: string maxLength: 128 pattern: ^[A-Za-z0-9-]{1,128}$ description: >- The Idempotency-Key BluMint sent with the create that made the lobby, exactly as sent: at most 128 ASCII letters, digits and -. Treat it as opaque and never parse it. PartnerReportPlayers: type: array minItems: 1 description: >- The team's players in a played game session, each by an in-game id BluMint sent and each optionally carrying its stats. Any one rostered id identifies the team. items: $ref: '#/components/schemas/PartnerReportPlayer' PartnerStats: type: object additionalProperties: true description: >- 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. PartnerRosterPlayers: type: array minItems: 1 description: >- The team's players, each by an in-game id BluMint sent and carrying no stats, because a termination or an abort reports no played game session. Any one rostered id identifies the team. items: $ref: '#/components/schemas/PartnerRosterPlayer' PartnerReportPlayer: allOf: - $ref: '#/components/schemas/PartnerRosterPlayer' - type: object properties: stats: $ref: '#/components/schemas/PartnerStats' PartnerRosterPlayer: type: object required: - inGameId properties: inGameId: type: string minLength: 1 maxLength: 256 description: >- An id BluMint sent for this player in the lobby's create, as a JSON string. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.