Repository navigation
REST API Reference
Kendo Tournament Manager exposes a REST API under the backend context path
(/kendo-tournament-backend in the Docker images). This page groups the
endpoints by functional area.
| Installation | Base URL |
|---|---|
| Source build (default) | http://localhost:8080/ |
| Docker images | https://<machine_domain>/kendo-tournament-backend/ |
Every request requires an Authorization: Bearer <token> header with a JWT
obtained from the login endpoints, except the public endpoints listed in
Authentication and users.
The JWT embeds the tenant (organization) selected at login. Do not try to specify a tenant per request, in a URL parameter or in a WebSocket topic: the backend rejects cross-tenant access automatically.
Authorizations are granted to the caller's active role:
| Role | Scope |
|---|---|
GUEST |
Temporary user logging in through a tournament QR code. |
PARTICIPANT |
Competitors logging in through a personal/stats QR code. |
VIEWER |
Read access inside the tenant. |
EDITOR |
Read + write access inside the tenant. |
ADMIN |
Administer users and tournament data inside the tenant. |
SUPER_ADMIN |
Platform role; only tenant management is available to it. |
Roles listed in the "Auth" column of this page are the ones authorized by the
endpoint (@PreAuthorize). Endpoints without an entry in that column require
any valid JWT (GUEST, PARTICIPANT, VIEWER, EDITOR, ADMIN).
JSON is used unless explicitly noted (application/pdf, image/png,
text/plain, multipart/form-data).
The whole authentication and user/tenant management API lives under the /auth base path.
| Method | Path | Auth | Description |
|---|---|---|---|
POST |
/auth/public/login |
public | Logs in. Body: {username, password, tenant}. The tenant is the organization name shown in the login screen. The JWT, expiration and session are returned in the response headers (Authorization, Expires, X-Session). |
POST |
/auth/public/login/guest |
public | Guest login. Body: {name, lastname, clubId, tournamentId}. Returns a GUEST JWT. |
POST |
/auth/public/participant/token |
public | Exchanges a temporal participant token (from a QR code) for a PARTICIPANT JWT. |
GET |
/auth/jwt/renew |
any | Renews the JWT. |
GET |
/auth/roles |
any | Returns the caller's roles. |
There is no logout endpoint: the client simply discards the JWT.
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/auth/register |
ADMIN |
Lists all users. |
POST |
/auth/register |
ADMIN |
Creates a user. The SUPER_ADMIN role cannot be assigned here. |
PATCH |
/auth/register |
ADMIN |
Updates a user. |
DELETE |
/auth/register/{username} |
ADMIN |
Deletes a user (ADMIN cannot delete itself). |
POST |
/auth/password |
any | Updates the caller's own password (old password required, throttled 0–10 s). |
POST |
/auth/{username}/password |
ADMIN |
Sets another user's password without the old one. |
See Tenancy for the concept. When the installation is configured
with tenancy disabled (Tenancy — Disabling tenancy),
all SUPER_ADMIN tenant endpoints below return 404.
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/auth/public/tenants |
public | Returns the organization name only when the platform has exactly one active tenant (used by the login screen auto-selection). With tenancy disabled it always returns ["Legacy organization"]. |
GET |
/auth/tenants |
SUPER_ADMIN |
Lists all tenants with id, name and active state. |
POST |
/auth/tenants |
SUPER_ADMIN |
Creates a tenant and its first ADMIN user. Body: {tenant, username, password, name, lastname}. Returns 201 with the new user and login headers; 409 if the tenant already exists. |
PATCH |
/auth/tenants/{tenantId} |
SUPER_ADMIN |
Renames or activates/deactivates a tenant. Body: {name, active}. |
DELETE |
/auth/tenants/{tenantId}/data |
SUPER_ADMIN |
Deletes all data of a tenant (users, clubs, participants, tournaments, teams, fights, results, statistics, images, including join tables) but keeps the tenant registration. Never touches other tenants. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/info/health-check |
public | Liveness probe. |
GET |
/info/latest-version |
public | Latest published version (text). |
GET |
/info/app-config |
public | Front-end configuration as JSON, e.g. {"tenancyEnabled": true}. |
GET |
/ |
public | Redirects to the Swagger UI (/swagger-ui/index.html). |
Besides the shared CRUD endpoints:
| Method | Path | Auth | Description |
|---|---|---|---|
POST |
/clubs/basic |
EDITOR |
Creates a club from name, country, city query parameters. |
POST |
/clubs/new-club |
EDITOR |
Creates a club from the full JSON body. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/participants/jwt |
any | Returns the participant data of the JWT user (self-service). |
POST |
/participants/temporal-token |
EDITOR |
Creates a short-lived temporal token used for QR login. |
| Method | Path | Auth | Description |
|---|---|---|---|
POST |
/tournaments/basic |
EDITOR |
Creates a tournament from name, shiaijos, teamSize, type. |
GET |
/tournaments/{tournamentId}/clone |
EDITOR |
Clones a tournament. |
PUT |
/tournaments/{tournamentId}/winners/{numberOfWinners} |
EDITOR |
Sets the number of winners passing from level 1 to level 2. |
GET |
/tournaments/unlocked/lasts |
any | Returns the last unlocked tournament. |
GET |
/tournaments/{tournamentId}/accreditations |
VIEWER |
All accreditations of a tournament as PDF (application/pdf). |
POST |
/tournaments/{tournamentId}/accreditations/{roleType} |
VIEWER |
Accreditation PDF for one role/participant. |
GET |
/tournaments/{tournamentId}/diplomas |
VIEWER |
All diplomas as PDF. |
POST |
/tournaments/{tournamentId}/diplomas |
VIEWER |
Diploma PDF for one participant. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/tournaments/properties/tournaments/{tournamentId} |
VIEWER |
Extra properties of a tournament. |
GET |
/tournaments/properties/tournaments/{tournamentId}/key/{key} |
VIEWER |
Single property by key. |
POST |
/tournaments/properties |
EDITOR |
Creates a tournament property. |
PUT |
/tournaments/properties |
EDITOR |
Updates a tournament property. |
GET |
/tournaments/properties/latest |
VIEWER |
Latest properties selected by the current user. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/teams/tournaments/{tournamentId} |
VIEWER |
All teams of a tournament. |
GET |
/teams/remaining/tournaments/{tournamentId} |
VIEWER |
Teams not disqualified (Senbatsu mode). |
GET |
/teams/tournaments/{tournamentId}/count |
VIEWER |
Number of teams in a tournament. |
POST |
/teams/tournaments |
VIEWER |
All teams of a tournament (body = TournamentDTO). |
PUT |
/teams/tournaments |
EDITOR |
Generates teams based on the tournament options. |
POST |
/teams/tournaments/delete |
EDITOR |
Deletes all teams of a tournament. |
POST |
/teams/set |
EDITOR |
Defines teams (replaces all teams of the tournament). |
POST |
/teams/delete/members |
EDITOR |
Deletes a member from any team. |
POST |
/teams/delete/members/all |
EDITOR |
Deletes multiple members. |
GET |
/teams/tournaments/{tournamentId}/pdf |
VIEWER |
Team list as PDF. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/fights/tournaments/{tournamentId} |
VIEWER |
All fights of a tournament. |
POST |
/fights/tournaments |
VIEWER |
All fights of a tournament (body = TournamentDTO). |
GET |
/fights/tournaments/{tournamentId}/pdf |
VIEWER |
Fights summary as PDF. |
GET |
/fights/tournaments/{tournamentId}/current |
VIEWER |
Current fight of a tournament. |
POST |
/fights/delete/tournaments |
EDITOR |
Deletes all fights of a tournament. |
PUT |
/fights/duels |
EDITOR |
Updates a fight and generates duels if missing. |
PUT |
/fights/create/tournaments/{tournamentId}/levels/{levelId} |
EDITOR |
Creates the fights of a level. |
PUT |
/fights/create/tournaments/{tournamentId}/next |
EDITOR |
Creates the next-round fights. |
GET |
/fights/competitor/{competitorId} |
VIEWER |
All fights involving a competitor. |
GET |
/fights/scores-from-name-to-center/tournaments/{tournamentId} |
VIEWER |
Checks the score sheet orientation (name → center). |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/groups/tournaments/{tournamentId} |
VIEWER |
All groups of a tournament. |
GET |
/groups/tournaments/{tournamentId}/level/{level}/index/{index} |
VIEWER |
Group by tournament, level and index. |
PUT |
/groups/{groupId}/teams |
EDITOR |
Sets the teams of a group. |
PATCH |
/groups/{groupId}/teams/add |
EDITOR |
Adds teams to a group. |
PATCH |
/groups/{groupId}/teams/delete |
EDITOR |
Removes teams from a group. |
PATCH |
/groups/tournaments/{tournamentId}/teams/delete |
EDITOR |
Removes teams from any group of a tournament. |
DELETE |
/groups/tournaments/{tournamentId}/teams/delete |
EDITOR |
Removes all teams from all groups of a tournament. |
PUT |
/groups/teams |
EDITOR |
Sets the teams of the first group. |
PUT |
/groups/{groupId}/unties |
EDITOR |
Adds untie duels to a group. |
GET |
/groups/tournaments/{tournamentId}/pdf |
VIEWER |
Group list as PDF. |
PATCH |
/groups/refresh/tournaments/{tournamentId}/levels/{level} |
VIEWER |
Recalculates teams/fights of the groups that have not started. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/duels/groups/{groupId}/unties |
VIEWER |
Untie duels of a group. |
GET |
/duels/tournaments/{tournamentId}/unties |
VIEWER |
Untie duels of a tournament. |
GET |
/duels/competitor/{competitorId} |
VIEWER |
Duels of a competitor. |
GET |
/duels/participant/{participantId}/unties |
VIEWER |
Untie duels involving a participant. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/roles/tournaments/{tournamentId} |
VIEWER |
All roles of a tournament. |
GET |
/roles/tournaments/{tournamentId}/pdf |
VIEWER |
Role/club list as PDF. |
GET |
/roles/tournaments/{id}/types/{roleTypes} |
VIEWER |
Roles filtered by type(s). |
POST |
/roles/delete/participants |
EDITOR |
Deletes a participant's role in a tournament. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/rankings/competitors/groups/{groupId} |
VIEWER |
Participants' ranking of a group. |
GET |
/rankings/competitors/tournaments/{tournamentId} |
VIEWER |
Participants' ranking of a tournament. |
POST |
/rankings/competitors |
VIEWER |
Global participants' ranking (body = participant list, from = minimum fights). |
GET |
/rankings/competitors/{competitorId} |
VIEWER |
Global ranking of one competitor. |
POST |
/rankings/competitors/pdf |
VIEWER |
Global participants' ranking as PDF. |
GET |
/rankings/competitors/clubs/{clubId} |
VIEWER |
Global ranking by club. |
GET |
/rankings/competitors/clubs/{clubId}/pdf |
VIEWER |
Global ranking by club as PDF. |
GET |
/rankings/competitors/tournaments/{tournamentId}/pdf |
VIEWER |
Tournament participants' ranking as PDF. |
GET |
/rankings/teams/groups/{groupId} |
VIEWER |
Teams' ranking of a group. |
GET |
/rankings/teams/tournaments/{tournamentId} |
VIEWER |
Teams' ranking of a tournament. |
GET |
/rankings/teams/tournaments/{tournamentId}/pdf |
VIEWER |
Tournament teams' ranking as PDF. |
GET |
/rankings/teams/groups/{groupId}/pdf |
VIEWER |
Group teams' ranking as PDF. |
GET |
/rankings/summary/{tournamentId}/html |
VIEWER |
Complete tournament summary (WordPress / blog HTML, text/plain). |
GET |
/rankings/tournament/{tournamentId}/zip |
VIEWER |
All result files (PDFs, HTML…) as a ZIP download. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/statistics/tournaments/{tournamentId}/fights |
VIEWER |
Fight statistics (calculateByTeams, calculateByMembers). |
GET |
/statistics/tournaments/{tournamentId} |
VIEWER |
Tournament statistics. |
GET |
/statistics/tournaments/{tournamentId}/previous/{number} |
VIEWER |
Statistics of the previous N tournaments. |
GET |
/statistics/participants/{participantId} |
VIEWER |
Participant lifetime statistics (participants see their own only). |
GET |
/statistics/participants/your-worst-nightmare/{participantId} |
VIEWER |
The "worst nightmare" (stats) of a participant. |
GET |
/statistics/participants/worst-nightmare-of/{participantId} |
VIEWER |
Participants for whom this one is the "worst nightmare". |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/achievements/participants/{participantId} |
VIEWER |
Achievements of a participant (participants see their own only). |
GET |
/achievements/tournaments/{tournamentId} |
VIEWER |
Achievements of a tournament. |
PATCH |
/achievements/tournaments/{tournamentId} |
EDITOR |
Regenerates the achievements of a tournament. |
PATCH |
/achievements/tournaments/all |
ADMIN |
Regenerates the achievements of all tournaments. |
GET |
/achievements/count/types |
VIEWER |
Total achievements by type/grade. |
GET |
/achievements/count/types/{achievementType} |
any | Count of achievements of one type. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/qr/guest/tournament/{tournamentId} |
VIEWER |
Guest-login QR code (base64) of a tournament. |
GET |
/qr/guest/tournament/{tournamentId}/png |
VIEWER |
Guest-login QR as PNG. |
GET |
/qr/guest/tournament/{tournamentId}/port/{port} |
VIEWER |
Guest-login QR with a specified frontend port. |
GET |
/qr/guest/tournament/{tournamentId}/port/{port}/png |
VIEWER |
Guest-login QR PNG with port. |
GET |
/qr/guest/tournament/{tournamentId}/pdf |
VIEWER |
Guest-login QR sheet as PDF. |
GET |
/qr/guest/tournament/{tournamentId}/pdf/port/{port} |
VIEWER |
QR sheet PDF with port. |
GET |
/qr/participant/{participantId}/statistics |
EDITOR |
Participant statistics-link QR code. |
GET |
/qr/participant/{participantId}/statistics/port/{port} |
EDITOR |
Participant statistics QR with port. |
POST |
/qr |
EDITOR |
Bare QR PNG from a text/plain body (attendance QR). |
POST |
/qr/svg |
EDITOR |
QR as SVG from a text/plain body. |
All endpoints store their errors as failed attempts in the response.
| Method | Path | Auth | Description |
|---|---|---|---|
POST |
/csv/clubs |
EDITOR |
Imports clubs from a file multipart. |
POST |
/csv/participants |
EDITOR |
Imports participants from a file multipart. |
POST |
/csv/teams |
EDITOR |
Imports teams (not linked to a tournament). |
POST |
/csv/teams/tournaments/{tournamentId} |
EDITOR |
Imports teams into a tournament. |
POST |
/csv/groups-link/tournaments/{tournamentId} |
EDITOR |
Imports championship arrows / group links of a tournament. |
Images are returned and accepted inside ParticipantImageDTO / TournamentImageDTO (JSON), or as multipart/form-data uploads.
| Method | Path | Auth | Description |
|---|---|---|---|
POST |
/files/participants/{participantId} |
VIEWER |
Uploads a participant photo (file multipart). |
POST |
/files/participants |
VIEWER |
Uploads a participant picture (JSON body). |
GET |
/files/participants/{participantId} |
VIEWER |
Gets a participant's image. |
DELETE |
/files/participants/{participantId} |
VIEWER |
Deletes a participant's image. |
POST |
/files/tournaments |
EDITOR |
Uploads a tournament image (JSON body). |
POST |
/files/tournaments/{tournamentId}/type/{imageType}/compression/{imageCompression} |
VIEWER |
Uploads a tournament image (multipart) with type and compression. |
GET |
/files/tournaments/{tournamentId}/type/{imageType} |
VIEWER |
Gets a tournament image. |
DELETE |
/files/tournaments/{tournamentId}/type/{imageType} |
VIEWER |
Deletes a tournament image. |
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/groups-links/tournament/{tournamentId} |
VIEWER |
All group links of a tournament. |
The links of a tournament can also be bulk-imported through POST /csv/groups-link/tournaments/{tournamentId}.
| Method | Path | Auth | Description |
|---|---|---|---|
DELETE |
/cache |
ADMIN |
Clears all server cache areas. |
POST |
/logger/info |
any | Logs an info message from the front-end. |
POST |
/logger/warning |
any | Logs a warning message. |
POST |
/logger/error |
any | Logs an error message. |
The clubs, participants, tournaments, teams, fights, duels, roles, groups and
achievements services inherit these generic endpoints for their own base path
({base}), with VIEWER/EDITOR/ADMIN as described below. The base paths
are: /tournaments, /participants, /teams, /fights, /duels, /roles,
/groups, /clubs, /achievements.
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
{base} |
VIEWER |
Gets all entities. |
POST |
{base}/ids |
VIEWER |
Gets the entities whose IDs are in the body collection. |
GET |
{base}/count |
any | Counts all entities. |
GET |
{base}/{id} |
VIEWER |
Gets one entity by id (participants additionally allow PARTICIPANT). |
POST |
{base} |
EDITOR |
Creates one entity (201). |
POST |
{base}/list |
EDITOR |
Creates a list of entities (201). |
DELETE |
{base}/{id} |
EDITOR |
Deletes one entity (204). |
POST |
{base}/delete |
EDITOR |
Deletes the entity sent in the body (204). |
POST |
{base}/delete/list |
EDITOR |
Deletes a collection (204). |
PUT |
{base} |
EDITOR |
Updates one entity. |
PUT |
{base}/all |
EDITOR |
Updates a list of entities. |
The complete OpenAPI/Swagger documentation of the running instance is
available at /swagger-ui/index.html.
Created by: softwaremagico