{ "openapi": "3.1.0", "info": { "title": "World Cup 2026 API", "version": "1.0", "description": "A full FIFA World Cup 2026 sandbox spanning the USA, Canada and Mexico: browse the 48-team format, compute live group standings, simulate matches with goal events, chase the Golden Boot, buy limited tickets (409 when sold out) and submit champion predictions." }, "servers": [ { "url": "https://funapi.dev/api/worldcup/v1" } ], "tags": [ { "name": "teams", "description": "national squads and groups" }, { "name": "matches", "description": "fixtures, simulation and VAR" }, { "name": "venues", "description": "2026 host stadiums" }, { "name": "players", "description": "Golden Boot race" }, { "name": "tickets", "description": "limited seats, real conflicts" }, { "name": "fanzone", "description": "mascots and predictions" } ], "paths": { "/teams": { "get": { "tags": [ "teams" ], "summary": "List qualified teams (filter by group, confederation or hosts)", "operationId": "wc-teams", "responses": { "200": { "description": "Team list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "group", "in": "query", "required": false, "schema": { "type": "string" }, "example": "A" }, { "name": "confederation", "in": "query", "required": false, "schema": { "type": "string" }, "example": "UEFA" }, { "name": "host", "in": "query", "required": false, "schema": { "type": "string" }, "example": "false" } ] } }, "/teams/{id}": { "get": { "tags": [ "teams" ], "summary": "Get one national team", "operationId": "wc-team", "responses": { "200": { "description": "Team", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Team not qualified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 6 } ] } }, "/groups/{letter}/standings": { "get": { "tags": [ "teams" ], "summary": "Live group standings computed from finished matches", "operationId": "wc-standings", "responses": { "200": { "description": "Standings", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid group letter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Group not seeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "letter", "in": "path", "required": true, "schema": { "type": "string" }, "example": "B" } ] } }, "/venues": { "get": { "tags": [ "venues" ], "summary": "List 2026 host stadiums, filter by country", "operationId": "wc-venues", "responses": { "200": { "description": "Venues", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Canada" } ] } }, "/venues/{id}": { "get": { "tags": [ "venues" ], "summary": "Get a stadium with its scheduled matches", "operationId": "wc-venue", "responses": { "200": { "description": "Venue", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown venue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/matches": { "get": { "tags": [ "matches" ], "summary": "List fixtures (filter by stage, status, group or team)", "operationId": "wc-matches", "responses": { "200": { "description": "Fixtures", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "stage", "in": "query", "required": false, "schema": { "type": "string" }, "example": "group" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "scheduled" }, { "name": "group", "in": "query", "required": false, "schema": { "type": "string" }, "example": "A" }, { "name": "teamId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/matches/{id}": { "get": { "tags": [ "matches" ], "summary": "Get one fixture with team and venue details", "operationId": "wc-match", "responses": { "200": { "description": "Fixture", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/matches/{id}/simulate": { "post": { "tags": [ "matches" ], "summary": "Kick off and simulate a match — updates score, goal events and standings (admin only)", "operationId": "wc-simulate", "responses": { "200": { "description": "Full-time result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Match already played", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Knockout pairing not decided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "wc26-group-b-opener" } ], "security": [ { "bearerAuth": [] } ] } }, "/matches/{id}/events": { "get": { "tags": [ "matches" ], "summary": "Goal timeline of a played match (409 before kickoff)", "operationId": "wc-match-events", "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Match not played yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/matches/{id}/var-review": { "get": { "tags": [ "matches" ], "summary": "Request a VAR review — the check takes ~3 seconds", "operationId": "wc-var", "responses": { "200": { "description": "VAR decision", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/players/top-scorers": { "get": { "tags": [ "players" ], "summary": "Golden Boot race — top scorers so far", "operationId": "wc-scorers", "responses": { "200": { "description": "Top scorers", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 5 } ] } }, "/tickets": { "post": { "tags": [ "tickets" ], "summary": "Buy match tickets — limited seats, 409 when sold out", "operationId": "wc-ticket-create", "responses": { "201": { "description": "Tickets confirmed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not enough seats left", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid category or quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "wc26-order-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "matchId": { "type": "integer" }, "category": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "matchId", "category", "quantity" ], "additionalProperties": false }, "example": { "matchId": 4, "category": "category-2", "quantity": 2 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets/{id}": { "get": { "tags": [ "tickets" ], "summary": "Get a ticket order (410 after cancellation)", "operationId": "wc-ticket", "responses": { "200": { "description": "Ticket order", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Order cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "tickets" ], "summary": "Cancel a ticket order and release the seats (admin only)", "operationId": "wc-ticket-cancel", "responses": { "204": { "description": "Cancelled" }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Already cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/predictions": { "post": { "tags": [ "fanzone" ], "summary": "Predict the 2026 world champion", "operationId": "wc-predict", "responses": { "201": { "description": "Prediction saved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "422": { "description": "Unknown team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nickname": { "type": "string" }, "championTeamId": { "type": "integer" }, "finalScore": { "type": "string" } }, "required": [ "nickname", "championTeamId", "finalScore" ], "additionalProperties": false }, "example": { "nickname": "qa_gu", "championTeamId": 6, "finalScore": "2-1" } } } } } }, "/predictions/leaderboard": { "get": { "tags": [ "fanzone" ], "summary": "Most-predicted champions", "operationId": "wc-leaderboard", "responses": { "200": { "description": "Leaderboard", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/fanzone/mascots": { "get": { "tags": [ "fanzone" ], "summary": "Meet Maple, Zayu and Clutch — the official 2026 mascots", "operationId": "wc-mascots", "responses": { "200": { "description": "Mascots", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Use qa-admin-token / qa-viewer-token, or a JWT from POST /auth/v1/login." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Cargo demo key: cargo-key-123." } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }