{"openapi":"3.0.3","info":{"title":"WC2026 API","description":"REST API for World Cup 2026 data — teams, groups, matches, stadiums, and post-match stats.\n\n## Authentication\nAll endpoints require an `Authorization: Bearer <key>` header. Get a key at [wc2026api.com](https://wc2026api.com).\n\n## Match Stats & Timeline\n`GET /matches/:id/stats` returns post-match stats (possession, shots, corners, fouls, cards) and a full event timeline (goals, own goals, yellow/red cards) for completed matches. Available within minutes of final whistle.\n\n## Live Scores\nMatch `status` and `score` fields update in real time during matches. The `phase` field tracks the current half: `PRE`, `1H`, `HT`, `2H`, `ET1`, `ET2`, `PEN`, `FT`, or `FT_PEN`.","version":"1.1.0"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{}},"paths":{"/teams":{"get":{"summary":"List all 48 teams","tags":["Teams"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string"},"flag_url":{"type":"string","nullable":true},"group_name":{"type":"string"}}}}}}}}}},"/teams/{id}":{"get":{"summary":"Get a team by ID","tags":["Teams"],"parameters":[{"schema":{"type":"integer"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string"},"flag_url":{"type":"string","nullable":true},"group_name":{"type":"string"}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/groups":{"get":{"summary":"List all 12 groups with their teams","tags":["Groups"],"responses":{"200":{"description":"Default Response"}}}},"/groups/{id}":{"get":{"summary":"Get a group by name (A–L) with standings","tags":["Groups"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Group letter, e.g. A"}],"responses":{"200":{"description":"Default Response"}}}},"/matches":{"get":{"summary":"List all matches","tags":["Matches"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"group","required":false,"description":"Filter by group letter (A–L)"},{"schema":{"type":"string"},"in":"query","name":"round","required":false,"description":"Filter by round: group, R32, R16, QF, SF, 3rd, final"},{"schema":{"type":"string"},"in":"query","name":"status","required":false,"description":"Filter by status: scheduled, live, completed"},{"schema":{"type":"string"},"in":"query","name":"team","required":false,"description":"Filter by team 3-letter code (e.g. BRA)"}],"responses":{"200":{"description":"Default Response"}}}},"/matches/{id}":{"get":{"summary":"Get a match by ID","tags":["Matches"],"parameters":[{"schema":{"type":"integer"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/matches/{id}/stats":{"get":{"summary":"Get post-match stats and timeline for a completed match","tags":["Matches"],"parameters":[{"schema":{"type":"integer"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/stadiums":{"get":{"summary":"List all host stadiums","tags":["Stadiums"],"responses":{"200":{"description":"Default Response"}}}},"/stadiums/{id}":{"get":{"summary":"Get a stadium by ID","tags":["Stadiums"],"parameters":[{"schema":{"type":"integer"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/test/match":{"get":{"summary":"Sandbox live match — test your live-score integration","tags":["Test"],"description":"Returns a **fictional** match that automatically cycles through every match phase every 160 minutes,\nanchored to UTC midnight: **PRE** → **1H** → **HT** → **2H** → **ET1** → **ET2** → **PEN** → **FT_PEN**.\n\nGoals at minutes **23** (BRA 1–0) and **67** (ARG 1–1). The match stays tied through extra time\nand is decided on penalties — **BRA 3–5 ARG**. Covers every state your client needs to handle.\n\n### `match_minute`\nCurrent minute of play (1–120). Included **only in this sandbox endpoint** — not available on\n`GET /matches` or `GET /matches/:id`. Use it to drive a match clock during testing.\n\n### `home_pen` / `away_pen`\nPenalty shootout scores. `null` for all phases before **PEN**. Mirrors the same fields on real\nmatch responses — `null` means no penalties, integers mean the match was decided on penalties.\n\n### `_sandbox`\nAlways `true`. Use this flag to distinguish test data from real data.\n\n### `next_phase_in_seconds`\nSeconds until the next phase begins. Useful for scheduling a re-fetch at the right moment.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Fictional live match in the current phase","content":{"application/json":{"schema":{"description":"Fictional live match in the current phase","type":"object","properties":{"_sandbox":{"type":"boolean","example":true},"id":{"type":"integer","example":9999},"match_number":{"type":"integer","example":999},"round":{"type":"string","example":"final"},"group_name":{"type":["null","string"],"example":null},"home_team":{"type":"string","example":"Brazil"},"home_team_code":{"type":"string","example":"BRA"},"home_team_flag":{"type":"string"},"away_team":{"type":"string","example":"Argentina"},"away_team_code":{"type":"string","example":"ARG"},"away_team_flag":{"type":"string"},"stadium":{"type":"string","example":"Estadio Azteca"},"stadium_city":{"type":"string","example":"Mexico City"},"stadium_country":{"type":"string","example":"Mexico"},"kickoff_utc":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","live","completed"]},"phase":{"type":"string","enum":["PRE","1H","HT","2H","ET1","ET2","PEN","FT_PEN"]},"match_minute":{"type":["null","integer"],"example":34,"description":"Current minute of play (1–120). Sandbox only."},"home_score":{"type":"integer","example":1},"away_score":{"type":"integer","example":1},"home_pen":{"type":["null","integer"],"example":3,"description":"Penalty shootout score for home team. null until PEN phase."},"away_pen":{"type":["null","integer"],"example":5,"description":"Penalty shootout score for away team. null until PEN phase."},"kickoff_in_seconds":{"type":["null","integer"],"description":"Seconds until kickoff (PRE only)."},"next_phase_in_seconds":{"type":"integer","description":"Seconds until the next phase begins."}}}}}}}}}},"security":[{"bearerAuth":[]}]}