/ DEVELOPERS

THE JOURNAL IS THE API

Coming 2027

Every mutation this site makes is already a typed journal event — 68 of them. Each one maps to a future POST below. The table renders from the same manifest the compiler checks: add an event without documenting it and the build fails. These docs cannot drift.

01 / WRITE — 68 EVENTS

Journal events as future POST endpoints
Method	Path	Event	Summary
POST	/v1/announcements/:id/pin	announcement.pinned	Pin or unpin an announcement.
POST	/v1/tournaments/:id/announcements	announcement.posted	Broadcast to entrants (fans out notifications).
POST	/v1/announcements/:id/react	announcement.reacted	Toggle a GG / ? / F sticker reaction.
POST	/v1/badges/unlock	badge.unlocked	Derived event — appended by replay when a rule fires; clients never post it.
POST	/v1/challenges/:id/accept	challenge.accepted	Accept and schedule a challenge.
POST	/v1/challenges/:id/decline	challenge.declined	Decline a challenge.
POST	/v1/challenges/:id/expire	challenge.expired	System: deadline passed — rungs swap, no immunity.
POST	/v1/ladders/:id/challenges	challenge.issued	Challenge up to 3 rungs above (24h response clock).
POST	/v1/challenges/:id/report	challenge.reported	Report the challenge result (winner takes the higher rung).
POST	/v1/comments/:id/delete	comment.deleted	Delete own comment (leaves a tombstone).
POST	/v1/comments/:id/edit	comment.edited	Edit within the 5-minute window.
POST	/v1/comments	comment.posted	Post a comment or depth-1 reply.
POST	/v1/comments/:id/report	comment.reported	Flag a comment.
POST	/v1/comments/:id/upvote	comment.upvoted	Toggle an upvote.
POST	/v1/matches/:id/dispute/resolve	dispute.resolved	Organizer resolves: uphold, overturn, or void.
POST	/v1/entries/:id/approve	entry.approved	Approve a pending entry (approval mode).
POST	/v1/entries/:id/checkin	entry.checked_in	Check in during the check-in window.
POST	/v1/entries/:id/decline	entry.declined	Decline a pending entry.
POST	/v1/entries/:id/dq	entry.disqualified	Disqualify an entrant with a reason.
POST	/v1/tournaments/:id/entries	entry.registered	Register a team or solo player.
POST	/v1/entries/:id/promote	entry.waitlist_promoted	Promote a waitlisted entry into the field.
POST	/v1/entries/:id/withdraw	entry.withdrawn	Withdraw from a tournament (mid-bracket: unplayed slots become byes).
POST	/v1/follows	follow.added	Follow a team, player, tournament, or channel.
POST	/v1/follows/remove	follow.removed	Unfollow.
POST	/v1/invites/:id/accept	invite.accepted	Accept a team invite.
POST	/v1/invites/:id/decline	invite.declined	Decline a team invite.
POST	/v1/invites/:id/revoke	invite.revoked	Revoke a pending invite.
POST	/v1/teams/:id/invites	invite.sent	Invite a user to the roster.
POST	/v1/ladders/:id/join	ladder.joined	Join a ladder at the bottom rung.
POST	/v1/matches/:id/confirm	match.confirmed	Opponent confirms the claim — the engine advances.
POST	/v1/matches/:id/dispute	match.disputed	Dispute a claim, optionally with a counter-claim.
POST	/v1/matches/:id/override	match.overridden	Organizer sets the result directly.
POST	/v1/matches/:id/report	match.reported	Submit a score claim (pending until confirmed; auto-confirms in 24h).
POST	/v1/matches/:id/reschedule	match.rescheduled	Move the scheduled time.
POST	/v1/matches/:id/reset	match.reset	Clear a result — downstream results cascade-revert.
POST	/v1/matches/:id/start	match.started	Mark a match live.
POST	/v1/matches/:id/walkover	match.walkover	Declare a walkover (forfeiting side still drops in double-elim).
POST	/v1/stages/:id/bulk-advance	matches.bulk_advanced	Walkover every selected ready match for the checked-in side.
POST	/v1/merch/orders	merch.ordered	Place a credit-funded merch order (demo fulfillment).
POST	/v1/notifications/read	notification.read	Mark one or all notifications read.
POST	/v1/tournaments/:id/pickem	pickem.submitted	Submit bracket predictions.
POST	/v1/tournaments/:id/pickem/update	pickem.updated	Update unlocked picks (locked picks reject).
POST	/v1/recruitment/:id/bump	recruitment.bumped	Bump to the top (once per 48h).
POST	/v1/recruitment/:id/close	recruitment.closed	Close as filled or withdrawn.
POST	/v1/recruitment	recruitment.posted	Post LFT/LFP with game-native role chips.
POST	/v1/recruitment/:id/respond	recruitment.responded	Respond to a post (notifies the author).
POST	/v1/rewards/:rewardId/claim	reward.claimed	Claim a reached level-milestone reward (grants store credits).
POST	/v1/scrims/:id/accept	scrim.accepted	Accept a request — both dashboards show the match block.
POST	/v1/scrims/:id/cancel	scrim.cancelled	Cancel an open scrim post.
POST	/v1/scrims	scrim.posted	Post a scrim with up to 3 time windows.
POST	/v1/scrims/:id/request	scrim.requested	Request a posted scrim.
POST	/v1/stages/:id/seeding/auto	seeding.auto	Auto-seed by rating or seeded random.
POST	/v1/stages/:id/seeding	seeding.reordered	Manually reorder seeds (pre-generation only).
POST	/v1/session	session.login	Start a session (demo persona in the mock world).
POST	/v1/session/logout	session.logout	End the session.
POST	/v1/settings	settings.updated	Patch user settings (theme, spoilers, motion, notifications).
POST	/v1/stages/:id/advancement	stage.advancement_edited	Edit the stage-to-stage seed map.
POST	/v1/stages/:id/generate	stage.generated	Lock entries and generate the bracket via the engine.
POST	/v1/stages/:id/regenerate	stage.regenerated	Force-rebuild a stage, discarding existing results.
POST	/v1/teams/:id/captain	team.captain_transferred	Transfer captaincy.
POST	/v1/teams	team.created	Create a team (creator becomes captain).
POST	/v1/teams/:id/disband	team.disbanded	Disband the team.
POST	/v1/teams/:id/edit	team.edited	Edit team identity and recruiting flag.
POST	/v1/tournaments/:id/cancel	tournament.cancelled	Cancel a tournament.
POST	/v1/tournaments/:id/clone	tournament.cloned	Clone structure and settings into a new draft.
POST	/v1/tournaments	tournament.created	Create a tournament draft (optionally from a template).
POST	/v1/tournaments/:id/edit	tournament.edited	Patch tournament details (format locked once live).
POST	/v1/tournaments/:id/publish	tournament.published	Open a draft for registration.

02 / READ — THE REPO SEAM

GET/v1/gamesGames with per-title vocabulary (maps, roles, stat profile).

GET/v1/tournaments?game=&status=&tier=Browse tournaments with facets.

GET/v1/tournaments/:slugTournament detail with stages and entries.

GET/v1/stages/:id/stateEngine stage truth — the bracket graph.

GET/v1/stages/:id/standingsDerived standings for any format.

GET/v1/matches?date=&live=Match hub — day pages and live now.

GET/v1/matches/:idSeries detail with games and participants.

GET/v1/rankings/:game?week=Weekly world rankings, 8-week archive.

GET/v1/leaderboards/:gamePlatform ladder ratings.

GET/v1/transfers?game=&window=Roster moves, rumors flagged.

GET/v1/circuits/:slug/standingsSeason standings folded from leg placements.

GET/v1/players/:slug/earningsCareer prize totals, equal roster split.

GET/v1/pickem/:tournament/summaryCommunity pick percentages per match.

GET/v1/comments?target=Threads for a match or article.

GET/v1/search?q=Cross-entity search documents.

03 / ONE DAY, THIS EXACT CALL

curl -X POST https://api.ggez.lk/v1/matches/m_4f2/report \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"result":{"kind":"series","winnerSlot":0,"gameScores":[[13,7],[13,11]]}}'

The payload shape is exactly what the demo writes to localStorage today. The backend swap changes the transport, not the contract.

/ Loading

Method

Path

Event

Summary

POST

/v1/announcements/:id/pin

announcement.pinned

Pin or unpin an announcement.

POST

/v1/tournaments/:id/announcements

announcement.posted

Broadcast to entrants (fans out notifications).

POST

/v1/announcements/:id/react

announcement.reacted

Toggle a GG / ? / F sticker reaction.

POST

/v1/badges/unlock

badge.unlocked

Derived event — appended by replay when a rule fires; clients never post it.

POST

/v1/challenges/:id/accept

challenge.accepted

Accept and schedule a challenge.

POST

/v1/challenges/:id/decline

challenge.declined

Decline a challenge.

POST

/v1/challenges/:id/expire

challenge.expired

System: deadline passed — rungs swap, no immunity.

POST

/v1/ladders/:id/challenges

challenge.issued

Challenge up to 3 rungs above (24h response clock).

POST

/v1/challenges/:id/report

challenge.reported

Report the challenge result (winner takes the higher rung).

POST

/v1/comments/:id/delete

comment.deleted

Delete own comment (leaves a tombstone).

POST

/v1/comments/:id/edit

comment.edited

Edit within the 5-minute window.

POST

/v1/comments

comment.posted