API reference

Sessions

A session is one tournament lobby: creating it provisions a Discord category, channels, and access role automatically; teams then sign up and matches are hosted inside it.

All paths are relative to https://api.zyron.pro/api/v1/guilds/:guildId. Team signup is covered on Teams; hosting and scoring on Matches & leaderboards.

List sessions

GET/guilds/:guildId/sessions

Field	Type	Description
`filter`	`"all" \| "upcoming" \| "previous"`	Query parameter. Default `all`.

Create a session

POST/guilds/:guildId/sessions

Creates the tournament and provisions Discord infrastructure: a category, its channels (signup, info, results), and the access role. Returns 201 Created; the response may include a warning string when provisioning partially succeeded (e.g. a missing bot permission).

Field	Type	Description
`name`required	`string`	Tournament name.
`teamSize`required	`"Solos" \| "Duos" \| "Trios" \| "Squad"`	Team format for the lobby.
`buildMode`required	`"build" \| "zeroBuild" \| "reload" \| "reloadZeroBuild"`	Gamemode family the hosted match loads into.
`startDate`required	`string`	ISO 8601 start time.
`endDate`required	`string`	ISO 8601 end time.
`accessRoleId`	`string`	Use an existing role for lobby access instead of creating one.
`adminRoleId`	`string`	Role that can administer this tournament.
`maxTeams`	`number`	Team cap; further signups go to the waitlist.
`priorityLevels`	`Array<{ roleIds: string[]; delaySeconds?: number }>`	Priority tiers, highest first. Each tier grants early signup to members holding ANY of roleIds, and opens delaySeconds after the previous tier (omit/null → priorityDelaySeconds). A plain string[] of role IDs is still accepted for backwards compatibility.
`priorityDelaySeconds`	`number`	Default per-tier delay (used when a tier omits delaySeconds) and the final wait before the access-role tier opens, in seconds.

curl -X POST https://api.zyron.pro/api/v1/guilds/123456789012345678/sessions \
  -H "Authorization: Bearer zyr_your_guild_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sunday Cup #12",
    "teamSize": "Duos",
    "buildMode": "zeroBuild",
    "startDate": "2026-07-19T18:00:00.000Z",
    "endDate": "2026-07-19T22:00:00.000Z",
    "maxTeams": 50
  }'

json

{
  "tournament": {
    "tournamentId": "t_7d31e0aa9c",
    "name": "Sunday Cup #12",
    "lobbyNumber": 12,
    "teamSize": "Duos",
    "buildMode": "zeroBuild",
    "startDate": "2026-07-19T18:00:00.000Z",
    "endDate": "2026-07-19T22:00:00.000Z",
    "maxTeams": 50,
    "status": "scheduled",
    "categoryId": "666666666666666666",
    "signupChannelId": "777777777777777777",
    "accessRoleId": "888888888888888888"
  },
  "warning": null
}

Get a session

GET/guilds/:guildId/sessions/:tournamentId

Returns the full tournament object, including its signup settings, match settings, dropmap block, and provisioning IDs.

Update a session

PATCH/guilds/:guildId/sessions/:tournamentId

Partial update — any of the setting blocks can be sent, individually or together:

Field	Type	Description
`session`	`object`	Lobby settings: `accessRoleId`, `priorityLevels`, `buildMode`.
`signup`	`object`	Signup settings: `maxTeams`, `requiredRoleIds`, `roleToPings`, `waitlistEnabled`.
`matchSettings`	`object`	Match settings: `region`, `rules`.
`dropmap`	`object`	Dropmap settings — see Dropmap.
`startDate / endDate`	`string`	Reschedule the tournament (ISO 8601).

The signup channel is server-authoritative

The lobby signup channel is created and managed by Zyron during provisioning and cannot be changed via PATCH. Everything else about the session is editable.

Delete a session

DELETE/guilds/:guildId/sessions/:tournamentId

Deletes the tournament and tears down its provisioned Discord category, channels, and role.

Registration actions

POST/guilds/:guildId/sessions/:tournamentId/open-registration

POST/guilds/:guildId/sessions/:tournamentId/close-registration

Open or close team signup. Opening fires the registration.opened webhook; closing fires registration.closed.

POST/guilds/:guildId/sessions/:tournamentId/open-fill

Field	Type	Description
`spots`	`number`	Optional number of fill spots to open; omit to open fill without a fixed count.

Opens fill signup so solo players can be matched into incomplete teams.

POST/guilds/:guildId/sessions/:tournamentId/cancel

Cancels the tournament and fires the session.cancelled webhook. Unlike DELETE, the record is kept for history.

Errors

400 invalid_request for a bad teamSize, buildMode, or date range; 404 not_found for an unknown tournamentId; 409 conflict for state conflicts (e.g. opening registration on a cancelled session). See Errors.