API reference

// Every public bracket for one game, biggest field first.
const { tournaments, total } = await client.listTournaments({
  scope: "public",
  game: "Rocket League",
  sort: "largest",
  limit: 10,
});
console.log(`${total} found`, tournaments.map((t) => t.name));

{
  "tournaments": [
    {
      "id": "0f1c...",
      "slug": "spring-invitational-Rk2p8Q",
      "name": "Spring Invitational",
      "game": "Rocket League",
      "format": "double_elim",
      "state": "underway",
      "visibility": "public",
      "participantCount": 16,
      "startedAt": "2026-08-11T18:00:00.000Z",
      "createdAt": "2026-08-10T09:12:41.000Z"
    }
  ],
  "total": 37,
  "limit": 24,
  "offset": 0
}

curl -X POST https://gauntletbrackets.com/api/v1/tournaments \
  -H "Authorization: Bearer gt_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2026-08-11-spring" \
  -d '{
    "name": "Spring Invitational",
    "game": "Rocket League",
    "format": "double_elim",
    "visibility": "public",
    "config": { "seedMethod": "standard", "grandFinalReset": true }
  }'

const tournament = await client.createTournament({
  name: "Spring Invitational",
  game: "Rocket League",
  format: "double_elim",
  visibility: "public",
  config: { seedMethod: "standard", grandFinalReset: true },
});

// The slug is derived from the name with a random suffix, so read it back
// rather than guessing it.
console.log(`Entries open at /t/${tournament.slug}`);

{
  "tournament": {
    "id": "0f1c...",
    "slug": "spring-invitational-Rk2p8Q",
    "name": "Spring Invitational",
    "format": "double_elim",
    "state": "pending",
    "visibility": "public",
    "participantCount": 0
  }
}

// A slug works anywhere an id does, so a URL someone sent you is enough.
const tournament = await client.getTournament("spring-invitational-a4f2");
if (tournament.state === "pending") console.log("Entries are still open");

{ "tournament": { "id": "0f1c...", "slug": "spring-invitational-Rk2p8Q", "state": "pending" } }

curl -X PATCH https://gauntletbrackets.com/api/v1/tournaments/spring-invitational-Rk2p8Q \
  -H "Authorization: Bearer gt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "unlisted" }'

// Going public once the schedule is settled. format and config are absent
// from the input type on purpose: changing either would invalidate every match.
await client.updateTournament(id, {
  visibility: "public",
  description: "Saturdays, 7pm UK. Best of three until the final.",
});

{ "tournament": { "id": "0f1c...", "visibility": "unlisted" } }

// Permanent, and it takes every participant, match and result with it.
// Archive instead if the bracket should stay readable.
await client.deleteTournament(id);

{ "deleted": true }

// Read as the owner, every entry carries its accessToken, so the magic links
// can be handed out again without having kept the creation response.
for (const team of await client.listParticipants(id)) {
  console.log(team.seed, team.name, team.accessToken);
}

{
  "participants": [
    { "id": "8b2e...", "name": "Team Vortex", "seed": 1, "checkedIn": false, "accessToken": "gtp_..." }
  ]
}

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/participants \
  -H "Authorization: Bearer gt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "names": ["Team Vortex", "Team Halcyon"] }'

const entered = await client.addParticipants(id, ["Team Vortex", "Night Owls"]);
for (const team of entered) {
  console.log(`${team.name}: https://gauntletbrackets.com/p/${team.accessToken}`);
}

{
  "participants": [
    { "id": "8b2e...", "name": "Team Vortex", "seed": 1, "accessToken": "gtp_..." },
    { "id": "5d71...", "name": "Team Halcyon", "seed": 2, "accessToken": "gtp_..." }
  ]
}

curl -X PATCH https://gauntletbrackets.com/api/v1/tournaments/$ID/participants \
  -H "Authorization: Bearer gt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "order": ["5d71...", "8b2e..."] }'

// Reseed by last season's finish. Send the finished order, every id once:
// a partial move would have to say what happens to what it displaces anyway.
const lastSeason: Record<string, number> = { "Team Vortex": 1, "Night Owls": 2 };

const roster = await client.listParticipants(id);
const seeded = [...roster].sort(
  // Anyone who did not play last season goes to the bottom, in roster order.
  (a, b) => (lastSeason[a.name] ?? 99) - (lastSeason[b.name] ?? 99),
);

await client.reorderParticipants(id, seeded.map((team) => team.id));

{
  "participants": [
    { "id": "5d71...", "name": "Team Halcyon", "seed": 1, "accessToken": "gtp_..." },
    { "id": "8b2e...", "name": "Team Vortex", "seed": 2, "accessToken": "gtp_..." }
  ]
}

curl -X PATCH https://gauntletbrackets.com/api/v1/tournaments/$ID/participants/$PARTICIPANT_ID \
  -H "Authorization: Bearer gt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Team Vortex Reserve" }'

// A typo fix, safe at any point in the event: matches reference the team by
// id, so this changes what everyone reads and moves nothing in the bracket.
await client.renameParticipant(id, participantId, "Night Owls");

{
  "participant": { "id": "8b2e...", "name": "Team Vortex Reserve", "seed": 1 }
}

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/participants/$PARTICIPANT_ID/link \
  -H "Authorization: Bearer gt_live_..."

// Someone pasted their link in the public channel. The old one stops working
// the moment this returns.
const team = await client.resetParticipantLink(id, participantId);
console.log(`New link for ${team.name}: https://gauntletbrackets.com/p/${team.accessToken}`);

{
  "participant": { "id": "8b2e...", "name": "Team Vortex", "seed": 1, "accessToken": "gtp_..." }
}

// A no-show, dropped before the bracket exists. Once it is generated the
// participant is referenced by matches and this is refused.
await client.removeParticipant(id, participantId);

{ "removed": "8b2e..." }

curl https://gauntletbrackets.com/api/v1/tournaments/$ID/admins \
  -H "Authorization: Bearer gt_live_..."

const { owner, admins } = await client.listAdmins(id);
console.log(`${owner?.username} plus ${admins.length} co-organiser(s)`);

{
  "owner": { "id": "1f0c...", "username": "gauntlet", "displayName": "You" },
  "admins": [
    { "id": "9a3d...", "username": "sam", "displayName": "Sam", "createdAt": "2026-08-12T13:00:00.000Z" }
  ]
}

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/admins \
  -H "Authorization: Bearer gt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "sam" }'

// By username, never by email: you should not need a colleague's address to
// work with them, and an endpoint taking one would confirm they have an account.
await client.addAdmin(id, "jordan");

{ "added": { "id": "9a3d...", "username": "sam" } }

curl -X DELETE "https://gauntletbrackets.com/api/v1/tournaments/$ID/admins?userId=$USER_ID" \
  -H "Authorization: Bearer gt_live_..."

// The list is what turns a username back into the id this call needs.
const { admins } = await client.listAdmins(id);
const leaving = admins.find((person) => person.username === "jordan");
if (leaving) await client.removeAdmin(id, leaving.id);

{ "removed": "9a3d..." }

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/signup \
  -H "Content-Type: application/json" \
  -d '{ "name": "Team Vortex", "joinCode": "ABCD2345" }'

// The entrant's side, from your own form. No credential at all.
const anyone = new GauntletClient({ baseUrl: "https://gauntletbrackets.com" });

const result = await anyone.signUp("spring-invitational-a4f2", {
  name: "Night Owls",
  joinCode: "ABCD2345", // only when registration is `invite`
});

console.log(result.status === "pending" ? "Waiting on the organiser" : "You are in");

{
  "status": "confirmed",
  "participant": { "id": "8b2e...", "name": "Team Vortex", "seed": 1 }
}

const waiting = await client.listSignups(id);
console.log(`${waiting.length} entries to review`);

{
  "signups": [
    { "id": "1f0c...", "name": "Team Meridian", "createdAt": "2026-08-12T09:00:00.000Z" }
  ]
}

// Clear the queue, oldest entry first. Each approval takes the next seed.
for (const entry of await client.listSignups(id)) {
  const team = await client.approveSignup(id, entry.id);
  console.log(`Seeded ${team.name} at ${team.seed}`);
}

{ "participant": { "id": "8b2e...", "name": "Team Meridian", "seed": 3 } }

// Frees the name, so someone else can enter under it.
await client.rejectSignup(id, signupId);

{ "rejected": "1f0c..." }

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/start \
  -H "Authorization: Bearer gt_live_..." \
  -H "Idempotency-Key: start-$ID"

// Seeds the field and locks the roster: pending to ready. Play is still
// closed, open() is the step that starts it.
const bracket = await client.generateBracket(id);
console.log(`${bracket.matches.length} matches, ${bracket.participants.length} teams`);

{
  "tournament": { "id": "0f1c...", "state": "ready", "startedAt": null },
  "participants": [ { "id": "8b2e...", "name": "Team Vortex", "seed": 1 } ],
  "matches": [
    {
      "id": "c40a...",
      "key": "W1-1",
      "side": "winners",
      "round": 1,
      "slot": 1,
      "label": "Winners round 1",
      "p1Id": "8b2e...",
      "p2Id": "5d71...",
      "state": "ready",
      "winnerToMatchId": "9ab3...",
      "winnerToSlot": 1,
      "version": 0
    }
  ]
}

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/open \
  -H "Authorization: Bearer gt_live_..."

// The deliberate go-live step. Until this runs every result is refused with
// a 409, which is what stops a mis-seeded bracket being played.
await client.open(id);

{
  "tournament": { "id": "0f1c...", "state": "underway", "startedAt": "2026-08-11T18:00:00.000Z" },
  "participants": [ { "id": "8b2e...", "name": "Team Vortex", "seed": 1 } ],
  "matches": [ { "id": "c40a...", "key": "W1-1", "state": "ready", "version": 0 } ]
}

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/reset \
  -H "Authorization: Bearer gt_live_..."

// Wrong seeding, caught before anyone played. Refused once the tournament is
// underway, so no reported result can be destroyed by it.
await client.reset(id);

{ "tournament": { "id": "0f1c...", "state": "pending", "startedAt": null } }

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/archive \
  -H "Authorization: Bearer gt_live_..."

// Off the shelf: still readable and still embeddable, closed to every write.
await client.archive(id);

{ "tournament": { "id": "0f1c...", "state": "complete", "archivedAt": "2026-08-11T20:00:00.000Z" } }

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/unarchive \
  -H "Authorization: Bearer gt_live_..."

// Reopens it to writes, for the correction that turned up a week later.
await client.unarchive(id);

{ "tournament": { "id": "0f1c...", "state": "complete", "archivedAt": null } }

// A now-playing board: just the matches an organiser has started.
const live = await client.getBracket(id, { state: ["underway"] });

// The default, for anything acting on the event: playing, playable or decided,
// with the empty future rounds left out.
const current = await client.getBracket(id);

// The whole graph, for drawing the bracket rather than acting on it.
const full = await client.getBracket(id, { matches: "all" });

{
  "tournament": { "id": "0f1c...", "format": "swiss", "state": "underway" },
  "participants": [ { "id": "8b2e...", "name": "Team Vortex", "seed": 1 } ],
  "matches": [ { "id": "c40a...", "key": "S1-1", "side": "swiss", "round": 1, "state": "complete" } ],
  "standings": [
    {
      "participant": "8b2e...",
      "rank": 1,
      "played": 3,
      "wins": 3,
      "losses": 0,
      "scoreFor": 9,
      "scoreAgainst": 2,
      "tiebreak": 5
    }
  ]
}

// Frames carry the reason, not the new state, so one code path renders the
// first load and every update after it.
const controller = new AbortController();

for await (const event of client.watch(id, { signal: controller.signal })) {
  if (event.event !== "bracket.updated") continue;

  const { matches } = await client.getBracket(id, { state: ["underway"] });
  console.log("on now:", matches.map((match) => match.label).join(", ") || "nothing");
}

// watch() does not reconnect, unlike a browser EventSource: it cannot send an
// Authorization header, which private tournaments need. Wrap it in a retry
// loop if the subscription has to outlive a network blip.

retry: 5000
event: ready
data: {"tournamentId":"0f1c..."}

event: bracket.updated
data: {"reason":"match.completed","matchId":"c40a..."}

: keepalive

curl -X POST https://gauntletbrackets.com/api/v1/matches/$MATCH/result \
  -H "Authorization: Bearer gt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "winnerId": "8b2e...",
    "games": [ { "p1Score": 3, "p2Score": 1 } ],
    "expectedVersion": 0
  }'

// expectedVersion makes this an optimistic write: a co-organiser who reported
// first causes a 409 instead of silently losing their result.
try {
  await client.reportResult(match.id, {
    winnerId: match.p1Id!,
    games: [{ p1Score: 3, p2Score: 1 }],
    expectedVersion: match.version,
  });
} catch (error) {
  if (error instanceof GauntletError && error.isVersionConflict) {
    const fresh = await client.getBracket(id);
    console.log("Someone reported it first:", fresh.matches.find((m) => m.id === match.id));
  } else {
    throw error;
  }
}

{
  "tournament": { "id": "0f1c...", "state": "underway" },
  "participants": [ { "id": "8b2e...", "name": "Team Vortex", "seed": 1 } ],
  "matches": [
    { "id": "c40a...", "state": "complete", "winnerId": "8b2e...", "version": 1 },
    { "id": "9ab3...", "state": "ready", "p1Id": "8b2e..." }
  ]
}

curl -X POST https://gauntletbrackets.com/api/v1/matches/$MATCH/underway \
  -H "Authorization: Bearer gt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "underway": true }'

// Cut the stream to the next match and say so on the bracket.
const { matches } = await client.getBracket(id, { state: ["ready"] });
const next = matches[0];
if (next) await client.setMatchUnderway(next.id, true);

// Called off, back to ready. Reporting a result clears it on its own, so this
// direction is for the match that never actually started.
if (next) await client.setMatchUnderway(next.id, false);

{ "match": { "id": "c40a...", "key": "W2-1", "state": "underway", "version": 0 } }

// The team's own side, using the gtp_ token from their magic link. One
// client per credential: this one can only see its own tournament.
const team = new GauntletClient({ baseUrl: "https://gauntletbrackets.com", token: "gtp_..." });

const outcome = await team.submitResult(matchId, {
  claimedWinnerId: myParticipantId,
  p1Score: 3,
  p2Score: 1,
});

// recorded: waiting on the opponent. confirmed: both agreed and the bracket
// moved. disputed: they did not, and an organiser now has to settle it.
console.log(outcome.status, outcome.message);

{
  "status": "confirmed",
  "message": "Both players agreed. The bracket has been updated."
}

// failureCount is the health signal. A subscriber that keeps failing is
// deactivated, so this is where you find out yours stopped receiving.
for (const hook of await client.listWebhooks(id)) {
  console.log(hook.url, hook.active ? "active" : "disabled", hook.failureCount);
}

{
  "webhooks": [
    {
      "id": "7cd2...",
      "url": "https://example.com/gauntlet",
      "eventTypes": ["match.completed"],
      "active": true,
      "failureCount": 0,
      "createdAt": "2026-08-10T09:20:00.000Z"
    }
  ]
}

curl -X POST https://gauntletbrackets.com/api/v1/tournaments/$ID/webhooks \
  -H "Authorization: Bearer gt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/gauntlet",
    "eventTypes": ["match.underway", "match.completed", "tournament.finished"]
  }'

// Everything a scoreboard needs: what went live, what finished, and what
// needs a human.
const hook = await client.createWebhook(id, {
  url: "https://example.com/gauntlet",
  eventTypes: ["match.underway", "match.completed", "match.disputed"],
});

// The only time the secret is ever returned, and it is what proves a later
// delivery came from Gauntlet. Put it somewhere your receiver can read it
// before you go any further; listing webhooks will not give it back.
console.log(`GAUNTLET_WEBHOOK_SECRET=${hook.secret}`);

{
  "webhook": {
    "id": "7cd2...",
    "url": "https://example.com/gauntlet",
    "eventTypes": ["match.completed", "tournament.finished"],
    "secret": "whsec_..."
  }
}

// Which account a key actually belongs to. A gtp_ participant token cannot
// read this; it is not an account.
const me = await client.getMe();
console.log(`Signed in as ${me.username}`);

{
  "user": {
    "id": "d21f...",
    "email": "you@example.com",  // session only; absent for an API key
    "displayName": "Gauntlet",
    "avatarUrl": "https://cdn.discordapp.com/avatars/...",
    "createdAt": "2026-08-01T12:00:00.000Z"
  }
}

// email and avatarUrl are absent from the input type on purpose: the identity
// provider owns both and refreshes them at every sign in.
await client.updateMe({ displayName: "Sam R." });

{ "user": { "id": "d21f...", "displayName": "Gauntlet" } }