diff --git a/doc/match_metadata_api.md b/doc/match_metadata_api.md
new file mode 100644
index 0000000..f516af8
--- /dev/null
+++ b/doc/match_metadata_api.md
@@ -0,0 +1,86 @@
+# 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`.
+
+```json
+{
+  "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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "match_ids": [1, 2, 5],
+  "start_time": "17:00"
+}
+```
+
+```json
+{
+  "group_stage_position": 1,
+  "start_time": "18:00"
+}
+```
+
+```json
+{
+  "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.