{ "openapi": "3.1.0", "info": { "title": "FIBA World Cup API", "version": "1.0", "description": "A FIBA Basketball World Cup 2027 sandbox in Qatar: 32 teams in eight groups, games simulated quarter by quarter with overtime, ETag-guarded team staff and box scores." }, "servers": [ { "url": "https://funapi.dev/api/fiba/v1" } ], "tags": [ { "name": "teams", "description": "the 32 qualified nations" }, { "name": "games", "description": "simulation, box scores and reviews" }, { "name": "arenas", "description": "the Doha host courts" }, { "name": "players", "description": "stat leaders and the MVP race" }, { "name": "tickets", "description": "limited seats, real conflicts" } ], "paths": { "/teams": { "get": { "tags": [ "teams" ], "summary": "List qualified teams (filter by group, FIBA zone or hosts)", "operationId": "fiba-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": "zone", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Europe" }, { "name": "host", "in": "query", "required": false, "schema": { "type": "string" }, "example": "false" } ] } }, "/teams/{id}": { "get": { "tags": [ "teams" ], "summary": "Get one national team — carries the ETag its staff update needs", "operationId": "fiba-team", "responses": { "200": { "description": "Team, with an ETag", "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": 32 } ] } }, "/teams/{id}/staff": { "put": { "tags": [ "teams" ], "summary": "Name the head coach and captain — optimistic concurrency via If-Match", "operationId": "fiba-team-staff", "responses": { "200": { "description": "Staff updated, etag bumped", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing coach, or a captain from another squad", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 32 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass the etag from GET /teams/{id} (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "headCoach": { "type": "string" }, "captainPlayerId": { "type": "number" } } }, "example": { "headCoach": "Ergin Ataman", "captainPlayerId": 63 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/groups/{letter}/standings": { "get": { "tags": [ "teams" ], "summary": "Group table computed from finished games — cacheable (ETag / If-None-Match / 304)", "operationId": "fiba-standings", "responses": { "200": { "description": "Standings, with ETag + Cache-Control", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "description": "Not Modified — If-None-Match matched" }, "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": "A" }, { "name": "If-None-Match", "in": "header", "required": false, "description": "Pass a prior etag; if no game has finished since, get 304 with no body.", "schema": { "type": "string" } } ] } }, "/arenas": { "get": { "tags": [ "arenas" ], "summary": "List the Qatar host arenas, filter by city", "operationId": "fiba-arenas", "responses": { "200": { "description": "Arenas", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "city", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Doha" } ] } }, "/arenas/{id}": { "get": { "tags": [ "arenas" ], "summary": "Get one arena with the games it hosts", "operationId": "fiba-arena", "responses": { "200": { "description": "Arena", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown arena", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/games": { "get": { "tags": [ "games" ], "summary": "List games (filter by stage, status, group or team)", "operationId": "fiba-games", "responses": { "200": { "description": "Games", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "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" } } ] } }, "/games/{id}": { "get": { "tags": [ "games" ], "summary": "Get one game with team and arena names resolved", "operationId": "fiba-game", "responses": { "200": { "description": "Game", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/games/{id}/simulate": { "post": { "tags": [ "games" ], "summary": "Tip off — four quarters plus overtime until somebody wins (admin only)", "operationId": "fiba-simulate", "responses": { "200": { "description": "Final score, quarter by quarter", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already played", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Knockout pairing not decided yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "fiba-game-1" } ], "security": [ { "bearerAuth": [] } ] } }, "/games/{id}/boxscore": { "get": { "tags": [ "games" ], "summary": "Per-player box score, derived from the play-by-play", "operationId": "fiba-boxscore", "responses": { "200": { "description": "Box score", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Game not played yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/games/{id}/play-by-play": { "get": { "tags": [ "games" ], "summary": "Cursor-paged play-by-play — follow nextCursor to the final buzzer", "operationId": "fiba-plays", "responses": { "200": { "description": "A page of plays and the next cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Cursor or limit out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Game not played yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 10 } ] } }, "/games/{id}/challenge": { "post": { "tags": [ "games" ], "summary": "Coach's challenge — a slow (~3s) replay review, one per team", "operationId": "fiba-challenge", "responses": { "200": { "description": "Review decision", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Game not played, or that bench already challenged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "team must be home or away", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "type": "string" }, "play": { "type": "string" } } }, "example": { "team": "home", "play": "Ball out of bounds at 2:14 of Q4" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/games/{id}/highlights": { "post": { "tags": [ "games" ], "summary": "Queue a highlight reel — 202 Accepted, then poll the job", "operationId": "fiba-highlights", "responses": { "202": { "description": "Render job accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Game not played yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "seconds must be 60, 120 or 300", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seconds": { "type": "number" } } }, "example": { "seconds": 120 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/highlights/{id}": { "get": { "tags": [ "games" ], "summary": "Poll a highlight job until it is ready", "operationId": "fiba-highlight-job", "responses": { "200": { "description": "Job state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/players": { "get": { "tags": [ "players" ], "summary": "List players (filter by team or position)", "operationId": "fiba-players", "responses": { "200": { "description": "Players", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "position", "in": "query", "required": false, "schema": { "type": "string" }, "example": "C" } ] } }, "/players/{id}": { "get": { "tags": [ "players" ], "summary": "Get one player with their running tournament totals", "operationId": "fiba-player", "responses": { "200": { "description": "Player", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown player", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 63 } ] } }, "/players/leaders": { "get": { "tags": [ "players" ], "summary": "Tournament leaders for points, rebounds or assists", "operationId": "fiba-leaders", "responses": { "200": { "description": "Leaderboard", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Unknown stat, or limit outside 1–20", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "stat", "in": "query", "required": false, "schema": { "type": "string" }, "example": "points" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 5 } ] } }, "/players/{id}/advanced": { "get": { "tags": [ "players" ], "summary": "Tracking data — always 402, it is on the paid analytics tier", "operationId": "fiba-advanced", "responses": { "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown player", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 63 } ] } }, "/fanzone/mvp": { "get": { "tags": [ "players" ], "summary": "The MVP race, ranked by a simplified efficiency index", "operationId": "fiba-mvp", "responses": { "200": { "description": "Top five by efficiency", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/tickets": { "post": { "tags": [ "tickets" ], "summary": "Buy tickets — seats are limited, so 409 when the game sells out", "operationId": "fiba-ticket-create", "responses": { "201": { "description": "Order confirmed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Unknown gameId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "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 tier or quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "fiba-order-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gameId": { "type": "number" }, "tier": { "type": "string" }, "quantity": { "type": "number" } } }, "example": { "gameId": 1, "tier": "lower", "quantity": 2 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets/{id}": { "get": { "tags": [ "tickets" ], "summary": "Get a ticket order — 410 once it has been cancelled", "operationId": "fiba-ticket", "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Order was cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "delete": { "tags": [ "tickets" ], "summary": "Cancel an order and release the seats", "operationId": "fiba-ticket-cancel", "responses": { "204": { "description": "Cancelled" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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": [] } ] } } }, "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 } } } }