Routes and integration notes
See the User Interface Help for task-oriented instructions and the English README for installation and configuration.
Table of contents
- API status
- Public GET routes
- Tournament visibility and ratings
- Authentication and member routes
- Administrative route groups
- Integration guidance
API status
Completed idempotency outcomes are retained for at least 90 days. New outcomes use UTC for retention; legacy outcomes with unknown timezones remain stored indefinitely to avoid premature expiry.
Submission reviewed_at is null for unreviewed submissions and historical reviews whose timezone is unknown; new web and API reviews expose a UTC timestamp.
The application remains server-rendered, with an authenticated API at /api/v1. The v1 operations are GET /me; player, ranking, match, tournament, participant, round, pairing, standings, and report reads; member result submissions; staff moderation; and tournament commands. GET /api/v1/openapi.json provides the full contract. Every API call requires a bearer token with the operation's scope and the account's current role permission. Create and manage personal tokens from the profile page: administrators choose a token's scopes, while every other account receives the scopes its current roles allow. The old draft paths /api/backup, /api/player, and /api/tournament are not implemented.
Operations are grouped into rollout slices that operators enable independently with API_ENABLED_SLICES; every slice is disabled by default. The slices are docs (OpenAPI), reads, submissions, moderation, tournament_setup (create/configure), tournament_participants, and tournament_rounds (rounds, results, processing). The OpenAPI document names each operation's slice in x-rollout-slice. A disabled slice returns 503 with code api_slice_disabled; a slice listed in API_STAFF_PILOT_SLICES returns 503 with api_pilot_restricted to non-staff accounts. Configuration, rollout order, and rollback are in the README.
Result submissions require Idempotency-Key; moderation decisions and conditional commands use If-Match with the current ETag. Tournament commands require the appropriate scope, permission, and geographic access. PairGo is always unrated and its games appear as pairings, not in individual match feeds. See the v1 contract for each operation’s requirements, limits, and effects.
Administrative actions are HTML form submissions. They require an authenticated session, the appropriate role, and a valid CSRF token. Some asynchronous admin actions return a small JSON redirect response only when the request includes X-Requested-With: XMLHttpRequest; this is an internal browser behavior, not a versioned API contract.
Public GET routes
These pages can be opened without an administrator account:
| Path | Purpose |
|---|---|
/ |
Home page, rankings summary, statistics, and published news |
/rankings |
Paginated public rankings |
/players |
Player directory and filters |
/player/view?id=<player_id> |
Player profile and match history |
/matches |
Match list and filters |
/tournaments |
Public tournament list |
/tournaments/<tournament_id> |
Public tournament details, pairings, and standings |
/tournaments/<tournament_id>/matches/<pairing_id> |
Public PairGo match details |
/reports |
Period and player reports |
/reports/export.csv |
CSV version of the selected report filters |
/reports/export.pdf |
PDF version of the selected report filters |
/category |
Glicko rating and category information |
/sgf-library |
Public SGF library |
/sgf-library/<filename> |
View metadata for an SGF record |
/sgf/<filename> |
Download an SGF record |
/matches/<match_id>/record |
View the SGF record linked to a match |
/matches/<match_id>/sgf |
Download the SGF record linked to a match |
/news/<article_id> |
Published news article |
Most pages accept an optional lang=es, lang=en, or lang=pt query parameter. /rankings accepts country (ISO 3166-1 alpha-3; legacy alpha-2 codes are also recognized), region=latam, and group=u18|women. Omitting region uses the administrator's configured region, initially Latin America; region=all or region= includes all regions. Filters intersect, so a country outside Latin America requires the all-region override when Latin America is the default. GET /api/v1/rankings uses the same configured default and region options; its repeated group filters use OR, whereas web group filters intersect. The u18 group also includes players marked Sub-18 with unknown birth year. Report pages also accept start_date, end_date, and player_id filters; see the user guide for examples.
Tournament visibility and ratings
API player last_active is the most recent played public individual game date, or null if none qualifies. Unrated individual games count; drafts, canceled games, PairGo, byes, absences, and invalid dates do not. GET /api/v1/players?last_active_days=N uses an inclusive cutoff from the application's current date, and sort=activity uses that same date. Web ranking activity filters use the same eligibility. Startup migration backfills existing dates; normal stats refresh and tournament visibility changes keep them current without changing rating eligibility.
Current behavior:
/tournamentslists active and completed tournaments. Organizers, Managers, and Administrators can also include drafts withshow_drafts=1; canceled tournaments are excluded from the list.- Canceled individual details remain accessible by direct web link and with
tournaments:readin the authenticated API. Canceled PairGo web detail pages remain staff-only. - Public match pages and profiles hide matches linked to draft or canceled tournaments. Player tournament histories include completed tournaments only.
- Rating recalculation includes standalone matches and matches linked to completed, rated tournaments. Matches from unrated, active, draft, or canceled tournaments do not affect ratings.
- PairGo is always unrated. Teams have two players without gender restrictions; their games appear in the web match list and both profiles but do not change individual statistics or head-to-head records.
- Changing a tournament status so completed games are added or removed marks the earliest affected date without recalculating ratings immediately. Use full recomputation or incremental replay in
/admin/ratingsto apply the change.
These rules apply to games linked through a tournament pairing; standalone matches continue to count toward ratings. See FUTURE_FEATURES.md for other remaining proposals.
Authentication and member routes
| Path | Method | Access |
|---|---|---|
/admin/login |
GET, POST | Sign in |
/admin/register |
GET, POST | Create a member account |
/admin/forgot-password |
GET, POST | Request a password-reset link |
/admin/reset-password/<token> |
GET, POST | Complete a password reset |
/admin/report-results |
GET, POST | Members submit results for their linked player or request a link to a player without an account |
/admin/profile |
GET, POST | Authenticated users manage their profile |
/admin/logout |
GET | End the current session |
Member submissions remain pending until reviewed. They do not affect public matches, ratings, or reports before approval.
Unlinked members post action=request_player_link and player_id through the CSRF-protected Report Results form. Player-link requests share the result moderation page and status filter. POST /admin/player-link-requests/<request_id>/approve and /reject require a Manager for the player's country/region or a global Administrator. Approval atomically links the still-available player, records the review/audit, and invalidates the member's existing sessions/tokens. Repeated or conflicting approvals do not overwrite links. Only one pending request per member is allowed; rejection permits a new request. These are web routes, not API resources.
Administrative route groups
All routes below require a signed-in account and role permissions. The forms and available actions are documented in User Interface Help.
/admin: administration dashboard/admin/analytics:GET /admin/analytics— administrator-only aggregate site analytics dashboard for the last 30 days/admin/import: Excel, CSV, and OpenGotha imports/admin/backups: create, restore, and delete managed backups/admin/players,/admin/players/import,/admin/matches: player and match management, including CSV/XLSX player import/admin/ratings,/admin/categories: rating and category configuration/admin/tournaments: tournament creation and management, including batch copying and deletion of up to 100 selected tournaments/admin/tournaments/<tournament_id>/...: participants, pairings, results, round processing, and export/admin/tournaments/<tournament_id>/participants/add-batchand/admin/tournaments/<tournament_id>/participants/remove-batch: enroll or remove up to 100 selected participants atomically/admin/sgf/...: SGF linking and deletion actions;/admin/sgf/delete-batchdeletes up to 100 selected files and clears linked match and pending-submission references/admin/news: news management/admin/users,/admin/audit,/admin/settings: account, audit, and application settings
The three staff access levels are Global, Regional, and Country. country_organizer and regional_organizer have Tournament Operations, including player creation through tournaments, editing/deletion, matches, SGF linking, and tournament workflows/imports. country_manager and regional_manager additionally have Data Management: player imports, news, and result moderation. Players and moderation are geographically filtered; a match needs at least one in-scope player, and a tournament an in-scope country. News is shared site-wide content. Country roles require a country (with linked-player fallback); regional roles require an explicit supported region. Incompatible or absent scopes deny geographic access. Administrators have global access.
The menu is organized by task rather than role: Players and competition, Imports and ratings, Content and game records, and Site administration. Permissions are unchanged: all backup operations, /admin/import, ratings/categories, users, audit, settings, and destructive SGF deletion remain administrator-only. Legacy operator and tournament_director accounts migrate to regional_manager and regional_organizer, respectively, assigned Latin America, with session/token invalidation. API reads preserve public visibility; draft tournament reads additionally require a current staff permission and matching geographic scope.
POST routes change application state and should be called through the rendered forms. OpenGotha uploads at either /admin/import or /admin/tournaments show the same review preview before explicit approval; the staged preview is bound to the user, uploaded file, and database state, and expires after 15 minutes. Batch actions require the same role permissions and CSRF protection as their single-item equivalents; tournament batch participant actions also require idempotency keys. Backup, restore, import, deletion, and tournament actions are deliberately not exposed as unauthenticated GET operations.
Integration guidance
For an external integration, use the documented authenticated API operations for available workflows and CSV/PDF report exports for other reports. Do not scrape admin forms or depend on undocumented JSON responses.
Milestones A0-A6 are complete; their procedures and observations are in the operations notes. The roadmap contains only pending proposals and verification. Use GET /api/v1/openapi.json for operation details, parameters, and schemas.
The approved OpenAPI 3.1 contract and its authentication, permission, and wire-format decisions are available in the API v1 contract and machine-readable OpenAPI document. Use a personal token with the exact scope named by each operation; tokens are sent only in the Authorization header over HTTPS. Under a path prefix such as /glicko, use the prefixed URLs returned in Location and in the OpenAPI servers entry.
Example request (PowerShell; keep the token in an environment variable, never in the URL):
$headers = @{ Authorization = "Bearer $env:GLICKO_API_TOKEN" }
Invoke-RestMethod -Uri "https://example.org/api/v1/rankings?per_page=5" -Headers $headers
To verify a deployment, run the standard-library smoke client with a pilot token. It sends only side-effect-free probes unless --write-draft-tournament is given, which creates one draft and should be used only against disposable data:
$env:GLICKO_API_TOKEN = "<pilot token>"
python scripts/api_smoke_test.py --base-url https://example.org --expect-enabled docs,reads --expect-disabled submissions,moderation,tournament_setup,tournament_participants,tournament_rounds
It prints a JSON report and exits with 0 when every check passes, 1 when a check fails, and 2 for invalid usage.