turniere-backend/doc/tournament_management_api.md

Tournament Management API Additions

This document covers tournament API additions that are not specific to timers, team action lists, or match metadata.

Related docs:

• timer_api.md
• team_action_lists_api.md
• match_metadata_api.md
• account_profiles_api.md

Tournament Metadata Fields

Tournaments support optional public metadata:

• location: venue, city, stream label, or other display location
• starts_at: tournament start timestamp
• ends_at: tournament end timestamp
• website_url: public URL for the tournament or event

These fields are included in:

• GET /tournaments
• GET /tournaments/:id?simple=true
• GET /tournaments/:id
• POST /tournaments
• PATCH /tournaments/:id
• leader/follower sync snapshots

Full and simple tournament responses include:

{
  "id": 11,
  "name": "Summer Cup",
  "code": "a1b2c3",
  "public": true,
  "location": "Main Hall",
  "starts_at": "2030-06-01T08:00:00Z",
  "ends_at": "2030-06-01T16:00:00Z",
  "website_url": "https://example.com/summer-cup"
}

Create With Metadata

Endpoint:

• POST /tournaments

{
  "name": "Summer Cup",
  "description": "Annual summer tournament",
  "public": true,
  "location": "Main Hall",
  "starts_at": "2030-06-01T10:00:00+02:00",
  "ends_at": "2030-06-01T18:00:00+02:00",
  "website_url": "https://example.com/summer-cup",
  "teams": [
    {
      "name": "Team Alpha"
    },
    {
      "name": "Team Beta"
    },
    {
      "name": "Team Gamma"
    },
    {
      "name": "Team Delta"
    }
  ]
}

Authentication:

• authenticated user required
• created tournament owner is the authenticated user

Update Metadata

Endpoint:

• PATCH /tournaments/:id

{
  "location": "Updated Arena",
  "starts_at": "2030-07-01T10:00:00+02:00",
  "ends_at": "2030-07-01T18:00:00+02:00",
  "website_url": "https://example.com/updated"
}

Authentication:

• tournament owner required
• read-only follower tournaments reject normal updates with 423

Validation:

• website_url must be blank or an http/https URL
• ends_at must be after starts_at when both are present
• location and website_url are stripped and stored as null when blank
• timestamp responses are serialized as ISO 8601 strings

Expected errors:

• 401 unauthenticated
• 403 authenticated but not owner
• 422 invalid metadata values
• 423 follower tournament is read-only

Delete Generated Group-Stage Playoffs

Use this endpoint when a tournament owner needs to reopen a finished group stage, change group-stage results, and regenerate playoffs.

Endpoint:

• DELETE /tournaments/:id/playoffs

Authentication:

• tournament owner required
• read-only follower tournaments reject with 423

Success response:

{
  "id": 11,
  "stages": [
    {
      "id": 21,
      "level": -1,
      "state": "in_progress"
    }
  ]
}

Success behavior:

• deletes all playoff stages for the group-stage tournament
• keeps the group stage
• changes the group stage back to in_progress
• enqueues tournament sync when configured
• broadcasts the normal tournament live update

Deletion is allowed only when:

• tournament has a group stage
• generated playoff stages exist
• every playoff match is still effectively unplayed
• playoff match states are not_started, not_ready, or single_team
• all playoff match scores and hidden scores are zero

Deletion is rejected after playoff play has started or scores have changed.

Expected statuses:

• 200 playoffs deleted
• 401 unauthenticated
• 403 authenticated but not tournament owner
• 404 tournament not found
• 422 no group stage, no generated playoffs, or playoffs no longer deletable
• 423 follower tournament is read-only

Common 422 errors:

• Only group-stage playoffs can be deleted
• Playoffs have not been generated
• Playoffs cannot be deleted after matches have started or scores changed

Existing Related Endpoints

Match scheduling/display metadata lives in match_metadata_api.md:

• PATCH /matches/:id
• PATCH /tournaments/:tournament_id/matches/metadata

Player account profile and team ownership APIs live in account_profiles_api.md:

• GET /accounts/:id
• GET /teams/:id
• PATCH /teams/:id
• PUT /teams/:id
• POST /tournaments team player_email / player_emails fields