turniere-backend/doc/match_metadata_api.md

Match Metadata API

Matches can store optional scheduling/display metadata:

• location: string, for venue, court, stream, or table
• start_time: string, for a local time like 17:00 or an agreed display value
• notes: free text for one-off match information

All fields are optional and nullable. Omitted fields are left unchanged.

Update One Match

Use PATCH /matches/:id to update metadata on one match. This endpoint still accepts the existing state transitions, and metadata can be sent with or without state.

{
  "location": "Main Hall",
  "start_time": "17:00",
  "notes": "Opening match. Stream setup needed."
}

Owner authentication is required. Read-only follower tournaments reject this with 423 Locked.

Bulk Update Matches

Use PATCH /tournaments/:tournament_id/matches/metadata to update metadata for multiple matches in one tournament.

At least one metadata field is required:

{
  "start_time": "18:00"
}

At least one selector is required:

• match_ids: explicit match ids in this tournament
• group_stage_position: all group stage matches at that match position
• stage_level: all playoff matches in that stage level
• stage_id: all matches in one stage
• position: all matches with that position
• state: all matches in that state, including upcoming
• all: true: every match in the tournament

Explicit ids take precedence over filters. Missing ids outside the tournament return 404 Not Found.

Examples:

{
  "match_ids": [1, 2, 5],
  "start_time": "17:00"
}

{
  "group_stage_position": 1,
  "start_time": "18:00"
}

{
  "stage_level": 3,
  "location": "Finals Arena",
  "start_time": "21:00",
  "notes": "Playoff wave"
}

Owner authentication is required. Read-only follower tournaments reject this with 423 Locked.

Follower Sync

location, start_time, and notes are part of tournament sync snapshots. Leader updates enqueue follower sync and live tournament broadcasts. Followers import these fields from the leader and remain read-only until takeover.