Tournaments

Registers your create-lobby callback URL.

Registers the https URL BluMint calls when a BluMint match is ready to play. Your endpoint creates a lobby, lets only the players listed in teams play, and answers with how they join, as you chose in the setup form: a link players open, a lobby code players type, or, if your own client puts the players in, a link the host can open to watch. In the setup form you also give the range of teams per match and of players per team your game server runs. A host can’t set up a tournament of your game outside those ranges, so every create you receive fits them, and the range of teams is exactly two on a best-of series. Ignore any field you do not recognise in a body BluMint sends you: BluMint can add a field at any time, so a server that refuses an unknown field stops working when one is added. Use and keep the player and spectator ids BluMint sends only to put players into matches in your game’s BluMint tournaments and to let the spectators who chose to watch do so. Share them with no one else, and keep them secure. Registering again replaces the previous URL. The URL’s host must resolve only to public addresses, an IP-address host must be a public IPv4 address, and BluMint follows no redirects, so the URL must answer directly.

Which answer to send when BluMint calls your URL:

Situation	Status	Code	Data field	What happens next
Created, or a repeat of a key already created	`200`			The players get the match and it starts.
You can’t match the id of a player the create names	`400`	`player_unlinked`	`players`	For a seat BluMint filled from an account the player linked on BluMint, such as a Lichess username, BluMint tells the player you didn’t recognize that account and retries under the same key every 60 seconds, so a retry can name an account you already refused. A player still unmatched when the tournament’s hold length runs out is disqualified. For a seat BluMint filled from your lookup, BluMint looks the named players up again and retries once under the same key. If you answer that retry with player_unlinked again, the host takes the match, and any other answer to it does what its own row says. If your lookup no longer finds a player, BluMint asks the player to connect their account and retries under the same key every 60 seconds. A player still unlinked when the tournament’s hold length runs out is disqualified. While the match is held, a player_unlinked on a looked-up seat keeps it held until the next retry.
A player the create names is still in another of your lobbies	`423`	`player_busy`	`players`	BluMint tells the named players to finish their other match and retries under the same key every 60 seconds. A player still busy when the tournament’s hold length runs out is disqualified.
You are down or overloaded	`502`, `503`, `504`, `408`, `429`, or no answer			The match keeps reading as being set up, and BluMint tells every player the create names once that you aren’t responding. BluMint retries under the same key every 60 seconds, or once the wait your Retry-After names has passed when that is later, waiting at most 5 minutes. If you are still down when the tournament’s hold length runs out, the host takes the match and nobody is disqualified.
You cannot run this match	`400`	`match_unsupported`		The host takes the match and starts it manually.
BluMint’s request breaks the rules in this guide	`400`	`invalid_request`		The host takes the match and starts it manually.
The key arrived with a different body, or a close already named it	`409`	`idempotency_key_reused`		The host takes the match and starts it manually.
Your server failed on this request	`500`			The host takes the match and starts it manually.

For what BluMint sends to your URL and how to answer it, see Create a lobby.

POST

tournaments

match

setCreate

Registers your create-lobby callback URL.

curl --request POST \
  --url https://staging.blumint.io/api/tournaments/match/setCreate \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "createMatchUrl": "https://www.yourgame.com/api/match/create"
}
'

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({createMatchUrl: 'https://www.yourgame.com/api/match/create'})
};

fetch('https://staging.blumint.io/api/tournaments/match/setCreate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://staging.blumint.io/api/tournaments/match/setCreate"

payload = { "createMatchUrl": "https://www.yourgame.com/api/match/create" }
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "Success - Match creation callback URL set successfully."
}

Authorizations

X-Api-Key

string

header

required

Body

application/json

createMatchUrl

string<uri>

required

The https URL of your create-lobby endpoint.

Example:

"https://www.yourgame.com/api/match/create"

authentication

object

The secret BluMint sends when it calls your create-lobby endpoint. When omitted, any secret registered earlier stays in place.

Show child attributes

Callbacks

POST

{$request.body#/createMatchUrl}matchCreation

Body

application/json

teams

object[]

required

Every team in the match, within the teams-per-match range you gave in the setup form, which is exactly two on a best-of series. Admit only these players, even when someone else learns the join link or lobby code.

Show child attributes

spectators

object[]

required

The host, streamers and moderators of the tournament who chose to watch, never a player in the match or anyone registered in the tournament. Always present, and empty when nobody is listed. It can list more spectators than your lobby admits. If your game supports watching, admit listed identities as spectators, in list order, until your lobby holds as many as it admits; a spectator can never play or report a result. Otherwise ignore the field. Never refuse a create because of its spectators.

Maximum array length: 16

Show child attributes

matchSettings

object

required

The match settings the host chose, passed to you unchanged, so hosts can run custom events of your game, such as a one-map tournament or a short time limit for a fast bracket. Its keys are the settings of your game you listed in the setup form. Set up the lobby with each one. An empty object means the host chose none, so use your defaults. Answer 400 match_unsupported for a setting you cannot run.

readyWithinSeconds

integer

required

The tournament's hold length in seconds, which the host sets between 5 and 30 minutes, 10 by default. BluMint tells every player to be ready this long after their match starts, or be disqualified, and BluMint times that itself. If your game ends a lobby on its own when a player doesn't show up, let that happen no earlier than this after you answer the create; otherwise ignore the field. The host can lengthen the hold while a match waits, so a repeat of one Idempotency-Key can carry a larger value. Leave it out when you compare a repeat's body.

Required range: 300 <= x <= 1800

series

object

Present on every best-of series create, and absent on single game sessions.

Show child attributes

Response

The lobby exists. Answer matchId and one of three ways for players to get in, the one your integration declared in the setup form. A join link: send matchUrl, which players open. A lobby code: send lobbyCode, which players type into your game. Neither, because your own game client puts players into the lobby: send spectateUrl, a watch link BluMint offers the host so they can follow the match. Send only the field of your own way in. A missing field, a field of another way in, or a link on another hostname fails the create for good: the host takes the match and starts it manually.

matchId

string

required

Your id for this lobby. BluMint treats it as opaque, sends it back unchanged, and you name it in every report.

Required string length: 1 - 256

matchUrl

string<uri>

On an integration whose players join by a link, the link players open, to a page on your site or your game client directly. It is https, carries no user:pass@, and its hostname is exactly one of the join-link hostnames you gave BluMint for this environment; a subdomain does not match. A lobby code in the fragment after # is fine, since BluMint sends the link byte for byte.

Maximum string length: 2048

lobbyCode

string

On an integration whose players join by a code, the code players type into your game, using only ASCII letters, digits, spaces, _, *, ., the backtick and -. BluMint shows it in chat, so it is never wrapped in *, _ or backticks and holds no link or email address.

Required string length: 1 - 32

spectateUrl

string<uri>

On an integration whose own game client puts players into the lobby, the https watch link BluMint offers the host, on one of the watch-link hostnames you gave BluMint. Anyone viewing the tournament can read it, so it lets its holder watch and nothing more: never play, control the match, or get the access you give the spectators listed in the create.

Maximum string length: 2048

Response

The create-lobby callback URL is registered.

message

string

required

Example:

"Success - Match creation callback URL set successfully."

Registers your create-lobby callback URL.

curl --request POST \
  --url https://staging.blumint.io/api/tournaments/match/setCreate \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "createMatchUrl": "https://www.yourgame.com/api/match/create"
}
'

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({createMatchUrl: 'https://www.yourgame.com/api/match/create'})
};

fetch('https://staging.blumint.io/api/tournaments/match/setCreate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://staging.blumint.io/api/tournaments/match/setCreate"

payload = { "createMatchUrl": "https://www.yourgame.com/api/match/create" }
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "Success - Match creation callback URL set successfully."
}

Overview

Endpoints

Registers your create-lobby callback URL.

Authorizations

Body

Callbacks

Body

Response

Response