API reference

There is no private admin API. Every screen in Gauntlet calls the endpoints below, so anything the site can do, your bot can do. All request and response bodies are JSON, all timestamps are ISO 8601 in UTC, and every path below is relative to https://gauntletbrackets.com.

On this page

TypeScript client

Optional. Everything on this page is plain HTTP and works from any language, but if you are writing TypeScript there is a published wrapper with types for every object, typed errors, and an async iterator over the live stream.

npm install @team-gauntlet/client

TypeScript

import { GauntletClient } from "@team-gauntlet/client";

const client = new GauntletClient({
  baseUrl: "https://gauntletbrackets.com",
  token: process.env.GAUNTLET_API_KEY, // gt_live_...
});

const tournament = await client.createTournament({
  name: "Spring Invitational",
  format: "double_elim",
});

await client.addParticipants(tournament.id, ["Team Vortex", "Team Halcyon"]);
await client.generateBracket(tournament.id); // pending to ready, roster locked
await client.open(tournament.id);            // ready to underway, results accepted

for await (const event of client.watch(tournament.id)) {
  if (event.event === "bracket.updated") render(await client.getBracket(tournament.id));
}

It has no runtime dependencies and calls exactly the endpoints below, so nothing it does is unavailable to curl. Failures throw a GauntletError carrying the same status, code and details documented in Errors. Key management is deliberately absent from it, because those endpoints accept an interactive session only.

Authentication

Send an API key as a bearer token. A key inherits its owner's tournaments and nothing else: it cannot touch a bracket its owner does not administer, and it cannot mint further keys. Browser sessions authenticate with a cookie instead, and participants with the cookie they get by opening their magic link.

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

Credential	How it arrives	What it can do
API key	Authorization: Bearer gt_live_...	Everything its owner can, minus minting keys
Session	httpOnly cookie from Discord sign in	Everything, including keys
Participant	httpOnly cookie from /p/<token>	Submit results for their own matches
None	No header, no cookie	Read public tournaments and search

Mint and revoke keys from your settings. Cookie-authenticated writes additionally require a same-origin request, so a third party page cannot make your browser act as you. Bearer-token callers are exempt, because a bot has no ambient cookie to abuse.

Idempotency

Send Idempotency-Key on any POST. A retry with the same key replays the original response instead of acting twice, so a dropped connection cannot advance a bracket twice. Reusing a key with a different body is rejected with 409, and a replayed response carries Idempotency-Replayed: true.

Concurrency

Include expectedVersion when reporting a result. If another organiser got there first you get 409 with the current version in details, rather than silently overwriting them. Refetch, decide, retry.

Errors

Every failure has the same shape, so one handler covers all of them.

{
  "error": {
    "code": "conflict",
    "message": "Match was updated by someone else",
    "details": { "currentVersion": 2 }
  }
}

Status	Code	Meaning
400	bad_request	Malformed JSON, or a field that failed validation. details carries the issues.
401	unauthorized	No credential, or one that has been revoked or expired.
403	forbidden	Authenticated, but not allowed to do this.
404	not_found	Missing, or hidden from this caller. The two are indistinguishable by design.
409	conflict	Version mismatch, reused idempotency key, or a wrong lifecycle state.
422	unprocessable	Valid JSON that the domain refuses, such as a roster over the cap.
422	invalid_bracket	The format engine rejected the request, such as too few entrants.
429	rate_limited	Over the limit. Retry-After says how long to wait.
500	internal_error	A bug on this end. Nothing further is disclosed.

Rate limits

Counted per credential, or per address for anonymous callers. Going over returns 429 with a Retry-After header.

Bucket	Limit	Applies to
Reads	300 / minute	Every GET, including embeds.
Writes	60 / minute	Result reports and other mutations.
Creates	20 / minute	Tournaments, participants, webhooks, starting a bracket.
Credentials	10 / minute	Minting keys and redeeming magic links.
Streams	60 / minute	Opening an SSE connection.

Objects

Responses are built from explicit allow-lists, so a new database column stays private until someone publishes it deliberately.

Tournament

Returned wherever a tournament appears. Secrets and owner ids are never included.

Field	Type	Description
id	string (uuid)	Stable identifier.
slug	string	URL segment, with an unguessable suffix.
name	string	Display name, up to 120 characters.
game	string \| null	Game or discipline.
description	string \| null	Free text, up to 2000 characters.
format	single_elim \| double_elim \| round_robin \| swiss	Fixed once the tournament is created.
config	object	Format options. See Format config.
state	pending \| ready \| underway \| complete \| cancelled	Lifecycle. Participants can only be added while pending. ready means the bracket exists but play has not been opened; results are refused until underway.
visibility	public \| unlisted \| private	Who may read it.
participantCount	integer	Entrants currently registered.
archivedAt	string (ISO 8601) \| null	Set when archived: closed to writes, still readable, hidden from public search. Independent of state.
embedUrl	string \| null	Iframe source for this bracket. Null for private tournaments.
startedAt	string (ISO 8601) \| null	When play was opened.
completedAt	string (ISO 8601) \| null	When the final was decided.
createdAt	string (ISO 8601)	Creation time.

Match

A node in the bracket graph. Advancement is a pointer walk: the winner is written into winnerToMatchId at winnerToSlot, and the loser into loserToMatchId, which is why every format advances identically.

Field	Type	Description
id	string (uuid)	Stable identifier.
key	string	Generator-stable key such as "W2-1" or "GF".
side	winners \| losers \| grand_final \| group \| swiss	Which part of the bracket the match belongs to.
round	integer	1-based round within that side.
slot	integer	Position within the round, top to bottom.
label	string	Human label, for example "Winners round 2".
groupKey	string \| null	Group identifier for round robin pools.
p1Id	string (uuid) \| null	Participant in slot 1, null until filled.
p2Id	string (uuid) \| null	Participant in slot 2, null until filled.
winnerId	string (uuid) \| null	Decided winner.
state	pending \| ready \| bye \| void \| complete \| disputed	ready means both slots are filled. disputed means the two reports disagreed.
walkover	boolean	True when the match resolved without being played.
winnerToMatchId	string (uuid) \| null	Where the winner advances.
winnerToSlot	1 \| 2 \| null	Which slot the winner fills.
loserToMatchId	string (uuid) \| null	Where the loser drops, double elimination.
loserToSlot	1 \| 2 \| null	Which slot the loser fills.
version	integer	Optimistic lock. Pass it back as expectedVersion when reporting a result.
completedAt	string (ISO 8601) \| null	When the result was recorded.

Participant

An entrant. The magic-link token appears once, in the creation response, and never again.

Field	Type	Description
id	string (uuid)	Stable identifier.
name	string	Display name, up to 80 characters.
seed	integer	1-based seed, assigned in insertion order.
checkedIn	boolean	Check-in flag. Listing only.
accessToken	string	Magic-link token. Creation response only, shown once, stored only as a hash.

Standings row

Included in the bracket response for round robin and Swiss.

Field	Type	Description
participant	string (uuid)	Participant id.
rank	integer	1-based, ties share a rank.
played	integer	Decided matches.
wins	integer	Matches won.
losses	integer	Matches lost.
scoreFor	integer	Points scored.
scoreAgainst	integer	Points conceded.
tiebreak	number	Median-Buchholz for Swiss, head to head otherwise.

Format config

The config object on a tournament. Every field is optional and each format ignores what does not apply to it.

Field	Type	Description
seedMethod	standard \| random \| as_entered	standard folds seeds 1 vs n. Defaults to standard.
thirdPlaceMatch	boolean	Single elimination only.
grandFinalReset	boolean	Double elimination. Adds the reset match.
groupCount	integer (1 to 32)	Round robin pools, snake seeded.
rounds	integer (1 to 32)	Swiss rounds. Defaults to ceil(log2(n)).
randomSeed	integer	Makes random seeding reproducible.

Tournaments

Create brackets, search public ones, and edit what has not been generated yet.

GET/api/v1/tournaments

List or search tournaments

With the default scope=mine this returns the tournaments the credential owns, at every visibility. With scope=public it searches published tournaments and needs no credential, which is exactly what the browse page calls.

Auth: Session or API key for scope=mine, none for scope=public

Query parameters

Field	Type	Description
scope	mine \| public	Defaults to mine.
q	string	Case-insensitive substring of the name or game. Up to 80 characters.
game	string	Case-insensitive substring of the game.
format	single_elim \| double_elim \| round_robin \| swiss	Exact format.
state	pending \| ready \| underway \| complete \| cancelled	Exact lifecycle state.
archived	exclude \| include \| only	Defaults to exclude. Honoured only for scope=mine; public search never returns archived tournaments.
sort	recent \| largest	Newest first, or most entrants first. Defaults to recent.
limit	integer (1 to 50)	Page size. Defaults to 24.
offset	integer (0 to 10000)	Rows to skip. Defaults to 0.

Response · 200 · Matching tournaments plus the total, so a caller can page without guessing.

{
  "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
}

Errors

Status	Code	When
401	unauthorized	scope=mine without a credential.

POST/api/v1/tournaments

Create a tournament

Creates a draft. No bracket exists yet, so format and config can still be chosen freely. The slug is derived from the name with a random suffix appended.

Auth: Session or API key with write scope

Headers

Field	Type	Description
Idempotency-Key	string	Up to 255 characters. A repeat with the same key replays the first response instead of acting twice.

Body

Field	Type	Description
name *	string (1 to 120)	Display name.
game	string (1 to 80)	Game or discipline.
description	string (up to 2000)	Free text shown on the public page.
format *	single_elim \| double_elim \| round_robin \| swiss	Cannot be changed once set.
visibility	public \| unlisted \| private	Defaults to public.
config	object	Format config. Defaults to {}.

* required

Example request

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 }
  }'

Response · 201 · The created tournament.

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

Errors

Status	Code	When
400	bad_request	A field is missing, too long, or unrecognised.
401	unauthorized	No credential, or a read-only API key.
409	conflict	The Idempotency-Key was reused with a different body.

GET/api/v1/tournaments/:id

Fetch one tournament

Accepts a UUID or a slug so links and API calls can share one route.

Auth: None for public, credential for unlisted or private

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Response · 200 · The tournament.

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

Errors

Status	Code	When
404	not_found	It does not exist, or the caller may not read it. Both answer the same way on purpose.

PATCH/api/v1/tournaments/:id

Update a tournament

format and config are deliberately not editable: changing either after a bracket exists would invalidate every generated match.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Body

Field	Type	Description
name	string (1 to 120)	New display name.
game	string (1 to 80)	New game.
description	string (up to 2000)	New description.
visibility	public \| unlisted \| private	New visibility.

Example request

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" }'

Response · 200 · The updated tournament.

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

Errors

Status	Code	When
400	bad_request	An unknown field was sent, including format or state.
404	not_found	Not yours, or not there.

DELETE/api/v1/tournaments/:id

Delete a tournament

Permanently removes the tournament and every participant, match, result and webhook belonging to it. Allowed in any state, including archived. There is no undo; archive instead if the bracket should stay readable.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Response · 200 · Confirmation.

{ "deleted": true }

Errors

Status	Code	When
404	not_found	Not yours, or not there.

Participants

Build the roster, and hand each entrant a link that lets them report their own results.

GET/api/v1/tournaments/:id/participants

List the roster

Ordered by seed. Access tokens are never included here.

Auth: Whoever may read the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Response · 200 · The roster.

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

POST/api/v1/tournaments/:id/participants

Add participants

Adds entrants in one call and returns a magic-link token for each. Seeds continue from the current roster size. Only possible while the tournament is a draft.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Headers

Field	Type	Description
Idempotency-Key	string	Up to 255 characters. A repeat with the same key replays the first response instead of acting twice.

Body

Field	Type	Description
names *	array of strings (1 to 256 entries)	Each name is 1 to 80 characters.

* required

Example request

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"] }'

Response · 201 · The created participants, each with a one-time accessToken.

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

Errors

Status	Code	When
409	conflict	The tournament has already started.
422	unprocessable	The roster would exceed 256 participants.

Send each entrant https://gauntletbrackets.com/p/<accessToken>. Opening it exchanges the token for an httpOnly cookie and redirects, so the secret leaves the URL bar, browser history and any Referer header.

Tokens are stored as SHA-256 hashes. Lose one and the fix is a new participant, not a lookup.

Bracket

Generate the bracket, read it, and watch it change.

POST/api/v1/tournaments/:id/start

Generate the bracket

Seeds the field, builds every match with its routing pointers, resolves byes, locks the roster, and moves the tournament from pending to ready. It does not begin play: results are refused until POST /open. Accepts an idempotency key.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Headers

Field	Type	Description
Idempotency-Key	string	Up to 255 characters. A repeat with the same key replays the first response instead of acting twice.

Example request

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

Response · 201 · The full bracket, identical in shape to GET /bracket without standings.

{
  "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
    }
  ]
}

Errors

Status	Code	When
409	conflict	The tournament is not pending, or is archived.
422	invalid_bracket	Too few participants for the chosen format.

POST/api/v1/tournaments/:id/open

Open for play

Moves a ready tournament to underway and stamps startedAt. Until this runs, every result endpoint refuses with 409. This is the deliberate go-live step: generating the bracket does not start the event.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Headers

Field	Type	Description
Idempotency-Key	string	Up to 255 characters. A repeat with the same key replays the first response instead of acting twice.

Example request

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

Response · 201 · The full bracket, with the tournament now underway.

{
  "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 } ]
}

Errors

Status	Code	When
409	conflict	The bracket has not been generated, or is already underway.

POST/api/v1/tournaments/:id/reset

Discard the bracket

Deletes every generated match and returns the tournament to pending so the roster can be edited and reseeded. Permitted only from ready: once a tournament is underway no action may destroy a reported result, and delete is the explicit way out.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Headers

Field	Type	Description
Idempotency-Key	string	Up to 255 characters. A repeat with the same key replays the first response instead of acting twice.

Example request

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

Response · 201 · The tournament, back in pending.

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

Errors

Status	Code	When
409	conflict	The tournament is pending, underway or complete.

POST/api/v1/tournaments/:id/archive

Status	Code	When
409	conflict	Already archived.

Unarchive

Clears archivedAt and reopens the tournament to writes.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Example request

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

Response · 201 · The tournament, with archivedAt cleared.

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

GET/api/v1/tournaments/:id/bracket

Fetch the bracket

Tournament, participants and every match. Round robin and Swiss also get a computed standings array.

Auth: Whoever may read the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Response · 200 · The bracket. standings is present only for round robin and Swiss.

{
  "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
    }
  ]
}

GET/api/v1/tournaments/:id/stream

Subscribe to live updates

A Server-Sent Events stream. One way traffic, so there is no upgrade handshake and no sticky sessions: EventSource reconnects on its own. A comment frame every 25 seconds keeps idle proxies from closing it.

Auth: Whoever may read the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Response · 200 · text/event-stream. A ready frame arrives immediately, then one frame per change.

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

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

: keepalive

Refetch GET /bracket when a bracket.updated frame arrives. Frames carry the reason, not the new state, so one code path renders both the first load and every update.

Rate limited to 60 new connections per minute per address, because viewers behind one office NAT share it.

Results

Two ways in: the organiser decides, or both teams agree.

POST/api/v1/matches/:id/result

Organiser reports a result

Sets the winner, writes the per-game scores, advances the winner and, in double elimination, drops the loser. Overrides participant submissions, which is how disputes get resolved.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string (uuid)	Match UUID, as returned in the bracket.

* required

Headers

Field	Type	Description
Idempotency-Key	string	Up to 255 characters. A repeat with the same key replays the first response instead of acting twice.

Body

Field	Type	Description
winnerId *	string (uuid)	Must be one of the two participants in the match.
games	array of { p1Score, p2Score } (up to 21)	Per-game scores. Each score is 0 to 999.
expectedVersion	integer	The match version you read. Omit to force the write and overwrite whoever got there first.

* required

Example request

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
  }'

Response · 201 · The whole bracket after advancement, so a client never has to reassemble it.

{
  "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..." }
  ]
}

Errors

Status	Code	When
404	not_found	No such match, or it belongs to someone else's tournament.
409	conflict	expectedVersion did not match. The current version comes back in details.
422	unprocessable	The winner is not in this match, or the match is not playable.

POST/api/v1/matches/:id/submit

Participant reports their own result

Records one side's claim. When both sides claim the same thing the bracket advances automatically. When they disagree the match is flagged disputed and left for an organiser.

Auth: Participant cookie, from a redeemed magic link

Path parameters

Field	Type	Description
id *	string (uuid)	Match UUID, as returned in the bracket.

* required

Body

Field	Type	Description
claimedWinnerId *	string (uuid)	Who the submitter says won.
p1Score *	integer (0 to 999)	Score for slot 1.
p2Score *	integer (0 to 999)	Score for slot 2.

* required

Response · 201 · status is recorded when waiting on the opponent, confirmed when both agreed and the bracket moved, or disputed when they did not.

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

Errors

Status	Code	When
401	unauthorized	No participant cookie.
403	forbidden	The participant is not in this match.
409	conflict	The match is already complete.

Webhooks

Push bracket changes to your own service, signed so you can trust them.

GET/api/v1/tournaments/:id/webhooks

List webhooks

Secrets are never listed back. Only the creation response has one.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Response · 200 · Registered endpoints and their delivery health.

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

POST/api/v1/tournaments/:id/webhooks

Register a webhook

The URL is resolved and checked before it is stored: anything pointing at a private or link-local address is refused, so this feature cannot be used to reach inside the network the server sits in. Ten webhooks per tournament.

Auth: Session or API key owning the tournament

Path parameters

Field	Type	Description
id *	string	Tournament UUID or slug. Both resolve to the same tournament.

* required

Body

Field	Type	Description
url *	string (https URL, up to 2000)	Where to POST deliveries.
eventTypes *	array of match.completed \| tournament.started \| tournament.finished \| match.disputed	At least one.

* required

Example request

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.completed", "tournament.finished"]
  }'

Response · 201 · The webhook, including the signing secret. Shown once.

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

Errors

Status	Code	When
422	unprocessable	The URL resolves to a private address, or 10 webhooks already exist.

Account

The signed-in account. There is no id parameter anywhere here on purpose.

GET/api/v1/me

Fetch your account

Who the current session belongs to.

Auth: Session only

Response · 200 · The account.

{
  "user": {
    "id": "d21f...",
    "email": "you@example.com",
    "displayName": "Capzay",
    "avatarUrl": "https://cdn.discordapp.com/avatars/...",
    "createdAt": "2026-08-01T12:00:00.000Z"
  }
}

Errors

Status	Code	When
401	unauthorized	No session.

PATCH/api/v1/me

Change your display name

Email and avatar are not editable: they come from the identity provider and are refreshed on every sign in, so a value set here would be reverted. Display name is the one field the account owns, and it is left alone by later sign ins.

Auth: Session only

Body

Field	Type	Description
displayName *	string (1 to 60)	What organisers and participants see.

* required

Response · 200 · The updated account.

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

Errors

Status	Code	When
400	bad_request	An unknown field was sent, including email.
401	unauthorized	No session, or an API key was used.

API keys

Credentials for your bot. Minted and revoked from an interactive login only.

GET/api/v1/keys

List active keys

Revoked keys are omitted. Only the prefix is stored, so a key cannot be recovered from here.

Auth: Session only

Response · 200 · Active keys.

{
  "keys": [
    {
      "id": "3a90...",
      "name": "Discord bot",
      "keyPrefix": "gt_live_9f2c",
      "scopes": ["read", "write"],
      "lastUsedAt": "2026-08-11T17:55:10.000Z",
      "expiresAt": null,
      "createdAt": "2026-08-01T12:00:00.000Z"
    }
  ]
}

POST/api/v1/keys

Mint an API key

An API key can never mint another key. Otherwise one leaked key is permanent: the attacker mints a fresh one and revoking the original achieves nothing. Twenty active keys per account.

Auth: Session only

Body

Field	Type	Description
name *	string (1 to 60)	What the key is for.
scopes	array of read \| write	Defaults to both.
expiresInDays	integer (1 to 365)	Omit for a key that does not expire.

* required

Response · 201 · The key. secret is shown once and stored only as a hash.

{
  "key": {
    "id": "3a90...",
    "name": "Discord bot",
    "keyPrefix": "gt_live_9f2c",
    "scopes": ["read", "write"],
    "secret": "gt_live_9f2c..."
  }
}

Errors

Status	Code	When
403	forbidden	The caller authenticated with an API key.
422	unprocessable	Twenty active keys already exist.

DELETE/api/v1/keys/:id

Revoke a key

A soft delete, so audit rows naming the key stay meaningful while investigating what it did.

Auth: Session only

Path parameters

Field	Type	Description
id *	string (uuid)	Key id.

* required

Response · 200 · Confirmation.

{ "revoked": true }

Errors

Status	Code	When
404	not_found	No such active key on this account.

Webhook signatures

Deliveries are POSTed as JSON with X-Gauntlet-Signature in the form t=<unix>,v1=<hex>, an HMAC-SHA256 over <timestamp>.<body> keyed with the secret from the creation response. Verify with a constant-time compare and reject timestamps older than five minutes, otherwise a captured delivery can be replayed at you forever.

TypeScript

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Event	Fires when
tournament.generated	The bracket has been generated and the roster locked.
tournament.started	The organiser opened the tournament for play.
match.completed	A result was recorded and the bracket advanced.
match.disputed	Two participants reported conflicting results.
tournament.finished	The final match is decided.

Every delivery body carries type, tournamentId and a data object. Endpoints resolving to private or link-local addresses are refused at registration, so a webhook cannot be pointed back inside the network the server runs in.

Embedding

One iframe, no script tag, no API key. The embed renders on the server and updates itself over SSE while the event runs. Every tournament payload carries its own embedUrl, so this is something you read off the API rather than a snippet to copy.

<iframe src="https://gauntletbrackets.com/embed/<slug>"
        width="100%" height="600" frameborder="0"
        title="Spring Invitational"></iframe>

Only public and unlisted tournaments can be framed. Every other route sends frame-ancestors 'none', so the organiser console cannot be wrapped in someone else's page and clicked through.