API Reference

Competition APIs exposed by the Tee Time backend (/api/competitions/*). Swagger is available at /api/docs.

Endpoint coverage

Category	Spec endpoints	Implemented	Notes
Competitions	11	11	✅ Complete
Entries	5	5	✅ Complete
Scorecards	5	6	✅ Complete (+unlock)
Draws	6	6	✅ Complete (tee-sheet sync)
Matchplay	5	5	✅ Complete (advance + hole record)
Side Competitions	3	3	✅ Complete (incl. 2’s club)
Series	5	5	✅ Complete (link/unlink)
Prizes	4	4	✅ Complete (template CRUD + pool/apply)
Appeals	4	4	✅ Complete (list/update/create)
Exports	1	1	✅ CSV export; PDF/WS not in scope here

Competitions

• POST /api/competitions — create competition (rounds, divisions, eligibility, posting mode, entry limits/fees).
• GET /api/competitions?clubId=&status=&seasonId= — list competitions for a club (status/season filters).
• GET /api/competitions/:id — competition detail (rounds, divisions, local rules, fees, eligibility, counts).
• PUT /api/competitions/:id — update competition metadata/settings.
• DELETE /api/competitions/:id — delete a draft/cancelled competition.
• POST /api/competitions/:id/publish — open competition for entries (DRAFT → OPEN).
• POST /api/competitions/:id/cancel — cancel competition (terminal state).
• POST /api/competitions/:id/finalize — finalize leaderboard positions (writes competitionResult + emits event).
• POST /api/competitions/:id/results/recalculate — recompute standings without changing status.
• GET /api/competitions/:id/stats — stats summary (entries, CSS, PCC, averages).
• Admin endpoints require teetime-admin audience (JWT): publish, cancel, finalize/recalc, bulk entries, draw operations, scorecard lock/unlock, admin tee-sheet sync.

Entries

• POST /api/competitions/:id/entries — create entry (supports divisionId, teamMembers, teeTimeSlotId, handicap provider/membership number, handicap override).
• POST /api/competitions/:id/entries/bulk — bulk import entries; returns successes/failures per player.
• GET /api/competitions/:id/entries?divisionId=&includeWithdrawn= — list entries for competition.
• GET /api/competitions/entries/:entryId — entry detail.
• POST /api/competitions/entries/:entryId/withdraw — withdraw entry (optional reason body).

Scorecards & scoring

• GET /api/competitions/rounds/:roundId/scorecards — list scorecards for a round (summaries).
• GET /api/competitions/scorecards/:id — scorecard detail with hole scores.
• PUT /api/competitions/scorecards/:id — update hole scores (gross/NR/pickup/putts/penalties).
• POST /api/competitions/scorecards/:id/attest — attest or dispute a submitted scorecard.
• POST /api/competitions/scorecards/:id/lock — lock an attested scorecard (triggers handicap posting when enabled).
• POST /api/competitions/scorecards/:id/unlock — admin unlock for corrections.

Leaderboards & exports

• GET /api/competitions/:id/leaderboard?divisionId= — leaderboard (positions, scores, withdrawals optionally excluded).
• GET /api/competitions/:id/leaderboard.csv?divisionId= — CSV export.

Draws & tee-sheet sync

• POST /api/competitions/:roundId/draw — generate draw for a round (body: drawType, groupSize, startTime, intervalMinutes, optional startingHoles). Path param :roundId is passed as the round identifier.
• DELETE /api/competitions/rounds/:roundId/draw — clear draw.
• POST /api/competitions/rounds/:roundId/draw/swap — swap two entries { entryAId, entryBId }.
• POST /api/competitions/rounds/:roundId/draw/move — move an entry { entryId, pairingId, position? }.
• POST /api/competitions/rounds/:roundId/draw/lock — lock draw.
• POST /api/competitions/rounds/:roundId/sync-tee-sheet — create entries from linked tee-sheet bookings (round must have teeSheetId).
• POST /api/competitions/admin/rounds/:roundId/sync-tee-sheet — admin-protected alias.

Side competitions

• POST /api/competitions/:id/nearest-pin / GET /api/competitions/:id/nearest-pin
• POST /api/competitions/:id/longest-drive / GET /api/competitions/:id/longest-drive
• GET /api/competitions/:id/twos-club

Matchplay

• POST /api/competitions/:id/matchplay/brackets — create bracket (name, matches).
• POST /api/competitions/:id/matchplay/brackets/seed — seed bracket from entries.
• GET /api/competitions/:id/matchplay/brackets/:bracketId — bracket detail.
• POST /api/competitions/:id/matchplay/brackets/:bracketId/advance — advance bracket.
• POST /api/competitions/matchplay/matches/:matchId/holes — record hole result.

Prize pools & templates

• POST /api/competitions/:id/prizes — allocate prizes to results.
• POST /api/competitions/clubs/:clubId/prize-templates — create prize template; GET /api/competitions/clubs/:clubId/prize-templates — list templates.
• GET /api/competitions/prize-templates/:templateId — template detail; POST /api/competitions/prize-templates/:templateId/delete — delete template.
• POST /api/competitions/:id/prize-pool — configure prize pool (tiers, mode, auto-allocate); GET /api/competitions/:id/prize-pool — fetch pool; POST /api/competitions/:id/prize-pool/auto-allocate — allocate by results.
• POST /api/competitions/:id/prize-pool/apply-template — apply template to a competition.

Appeals

• POST /api/competitions/:id/appeals — create appeal for a competition.
• POST /api/competitions/appeals/:appealId — update appeal.
• GET /api/competitions/:id/appeals — list appeals for competition.

Series (Order of Merit / leagues)

• POST /api/competitions/series — create series.
• POST /api/competitions/series/:seriesId — update series.
• GET /api/competitions/series/:seriesId — series detail (linked competitions).
• GET /api/competitions/series/:seriesId/standings?limit=&offset= — standings with pagination.
• POST /api/competitions/series/:seriesId/recalculate — recompute standings.
• POST /api/competitions/series/:seriesId/link / POST /api/competitions/series/:seriesId/unlink — link/unlink competition.

Association course mappings

• POST /api/competitions/clubs/:clubId/course-mappings — upsert course mapping to GolfRSA/DotGolf (provider, associationCourseId, optional layout/tee colour).
• GET /api/competitions/clubs/:clubId/course-mappings?provider= — list mappings (optionally filter by provider).