openapi: 3.0.3
info:
  title: KickoffAPI v2 — Native Football Data API
  version: 2.0.0
  description: >
    KickoffAPI's native API. Uses KickoffAPI's own stable identifiers
    (e.g., `lg_...`, `tm_...`, `fx_...`, `pl_...`, `vn_...`) and a unified `{ data, meta }` response envelope.
    Supports cursor pagination, in-house statistical models (Dixon-Coles, xG), AI match previews/recaps, and full backward-compatible legacy ID resolution.
    
    **Authentication:** Pass your API key in the `x-api-key` HTTP header.
servers:
  - url: https://api.kickoffapi.com
security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

  schemas:
    Meta:
      type: object
      properties:
        count: { type: integer, example: 50 }
        cursor: { type: integer, example: 0 }
        nextCursor: { type: string, nullable: true, example: "50" }
        source: { type: string, example: "kickoffapi-derived" }

    ErrorResponse:
      type: object
      properties:
        error: { type: string, example: "fixture not found" }

    Country:
      type: object
      properties:
        name: { type: string, example: "England" }
        code: { type: string, example: "GB" }
        flag: { type: string, example: "https://cdn.kickoffapi.com/images/flags/gb.svg" }

    League:
      type: object
      properties:
        id: { type: string, example: "lg_8K3mZ0pQ" }
        name: { type: string, example: "Premier League" }
        type: { type: string, example: "League" }
        country: { type: string, example: "England" }
        logo: { type: string, example: "https://cdn.kickoffapi.com/images/leagues/39.png" }

    Team:
      type: object
      properties:
        id: { type: string, example: "tm_a1B2c3" }
        name: { type: string, example: "Arsenal" }
        country: { type: string, example: "England" }
        logo: { type: string, example: "https://cdn.kickoffapi.com/images/teams/42.png" }

    Player:
      type: object
      properties:
        id: { type: string, example: "pl_x9Y8z7" }
        name: { type: string, example: "Bukayo Saka" }
        firstname: { type: string, example: "Bukayo" }
        lastname: { type: string, example: "Saka" }
        age: { type: integer, example: 24 }
        nationality: { type: string, example: "England" }
        photo: { type: string, example: "https://cdn.kickoffapi.com/images/players/1460.png" }

    Venue:
      type: object
      properties:
        id: { type: string, example: "vn_77K2p" }
        name: { type: string, example: "Emirates Stadium" }
        city: { type: string, example: "London" }
        capacity: { type: integer, example: 60704 }
        image: { type: string, example: "https://cdn.kickoffapi.com/images/venues/494.png" }

    FixtureStatus:
      type: object
      properties:
        long: { type: string, example: "Match Finished" }
        short: { type: string, example: "FT" }
        elapsed: { type: integer, example: 90 }

    FixtureScore:
      type: object
      properties:
        home: { type: integer, example: 2 }
        away: { type: integer, example: 1 }
        halftime:
          type: object
          properties:
            home: { type: integer, example: 1 }
            away: { type: integer, example: 0 }

    Fixture:
      type: object
      properties:
        id: { type: string, example: "fx_99Xy" }
        date: { type: string, format: date-time, example: "2026-06-27T16:30:00Z" }
        status: { $ref: '#/components/schemas/FixtureStatus' }
        league:
          type: object
          properties:
            id: { type: string, example: "lg_8K3mZ0pQ" }
            name: { type: string, example: "Premier League" }
            season: { type: integer, example: 2026 }
        home: { $ref: '#/components/schemas/Team' }
        away: { $ref: '#/components/schemas/Team' }
        score: { $ref: '#/components/schemas/FixtureScore' }

    FixtureEvent:
      type: object
      properties:
        time: { type: object, properties: { elapsed: { type: integer }, extra: { type: integer, nullable: true } } }
        team: { $ref: '#/components/schemas/Team' }
        player: { type: object, properties: { id: { type: string }, name: { type: string } } }
        type: { type: string, example: "Goal" }
        detail: { type: string, example: "Normal Goal" }

    FixtureLineup:
      type: object
      properties:
        team: { $ref: '#/components/schemas/Team' }
        formation: { type: string, example: "4-3-3" }
        startXI: { type: array, items: { type: object } }
        substitutes: { type: array, items: { type: object } }
        coach: { type: object, properties: { id: { type: string }, name: { type: string } } }

    FixtureStatistic:
      type: object
      properties:
        team: { $ref: '#/components/schemas/Team' }
        statistics: { type: array, items: { type: object, properties: { type: { type: string }, value: { type: string } } } }

    StandingRow:
      type: object
      properties:
        rank: { type: integer, example: 1 }
        team: { $ref: '#/components/schemas/Team' }
        points: { type: integer, example: 86 }
        goalsDiff: { type: integer, example: 45 }
        played: { type: integer, example: 38 }
        win: { type: integer, example: 27 }
        draw: { type: integer, example: 5 }
        lose: { type: integer, example: 6 }
        form: { type: string, example: "WWWDW" }

    LeaderboardRow:
      type: object
      properties:
        rank: { type: integer, example: 1 }
        player: { $ref: '#/components/schemas/Player' }
        team: { $ref: '#/components/schemas/Team' }
        goals: { type: integer, example: 27 }
        assists: { type: integer, example: 14 }

    OddsRow:
      type: object
      properties:
        fixtureId: { type: string, example: "fx_99Xy" }
        bookmaker: { type: object, properties: { id: { type: integer }, name: { type: string } } }
        betType: { type: object, properties: { id: { type: integer }, name: { type: string } } }
        values: { type: array, items: { type: object, properties: { value: { type: string }, odd: { type: string } } } }

    Transfer:
      type: object
      properties:
        date: { type: string, example: "2026-07-01" }
        type: { type: string, example: "Free" }
        player: { $ref: '#/components/schemas/Player' }
        teamIn: { $ref: '#/components/schemas/Team' }
        teamOut: { $ref: '#/components/schemas/Team' }

    Injury:
      type: object
      properties:
        player: { $ref: '#/components/schemas/Player' }
        team: { $ref: '#/components/schemas/Team' }
        fixture: { type: object, properties: { id: { type: string } } }
        type: { type: string, example: "Hamstring" }
        reason: { type: string, example: "Thigh Muscle Strain" }

    Coach:
      type: object
      properties:
        id: { type: string, example: "ch_9812" }
        name: { type: string, example: "Mikel Arteta" }
        team: { $ref: '#/components/schemas/Team' }
        photo: { type: string }

    Trophy:
      type: object
      properties:
        league: { type: string, example: "Premier League" }
        season: { type: string, example: "2023/2024" }
        place: { type: string, example: "Winner" }

    Projection:
      type: object
      properties:
        fixture: { type: string, example: "fx_99Xy" }
        homeWinProb: { type: number, example: 0.54 }
        drawProb: { type: number, example: 0.24 }
        awayWinProb: { type: number, example: 0.22 }
        expectedGoalsHome: { type: number, example: 1.85 }
        expectedGoalsAway: { type: number, example: 1.15 }

    MatchContent:
      type: object
      properties:
        id: { type: string, example: "fx_99Xy" }
        preview: { type: string, example: "Arsenal host Chelsea in a critical derby encounter..." }
        recap: { type: string, example: "Arsenal secured a 2-1 victory following a late winner..." }

    XgOutput:
      type: object
      properties:
        xg: { type: number, example: 0.32 }
        distance: { type: number, example: 14.2 }
        angleDegrees: { type: number, example: 38.5 }

paths:
  /api/v2/countries:
    get:
      summary: List Countries
      description: Retrieve list of all supported countries, ISO codes, and flag images.
      parameters:
        - { name: limit, in: query, schema: { type: integer, default: 50, maximum: 200 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: List of countries returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Country' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/leagues:
    get:
      summary: List Leagues
      description: Retrieve football leagues filtered by country or status.
      parameters:
        - { name: country, in: query, schema: { type: string }, description: "Filter by country name (e.g., England)" }
        - { name: limit, in: query, schema: { type: integer, default: 50, maximum: 200 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: List of leagues returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/League' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/teams:
    get:
      summary: List Teams
      description: Retrieve teams filtered by country.
      parameters:
        - { name: country, in: query, schema: { type: string }, description: "Filter by country name" }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: List of teams.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Team' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/fixtures:
    get:
      summary: List Fixtures & Scores
      description: Fetch scheduled or live football matches. Accepts native IDs (`lg_...`, `tm_...`) or legacy IDs.
      parameters:
        - { name: league, in: query, schema: { type: string }, description: "League native ID (e.g. lg_8K3mZ0pQ) or integer ID" }
        - { name: season, in: query, schema: { type: integer }, description: "Season year (e.g. 2026)" }
        - { name: date, in: query, schema: { type: string, format: date }, description: "Date string (YYYY-MM-DD)" }
        - { name: from, in: query, schema: { type: string, format: date }, description: "Range start date (YYYY-MM-DD)" }
        - { name: to, in: query, schema: { type: string, format: date }, description: "Range end date (YYYY-MM-DD)" }
        - { name: team, in: query, schema: { type: string }, description: "Team native ID or integer ID" }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Array of fixtures matching search filters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Fixture' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/fixtures/{id}:
    get:
      summary: Single Fixture Details
      description: Get detailed match information along with embedded AI match preview & recap summaries.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string }, description: "Fixture native ID (fx_...) or integer ID" }
      responses:
        '200':
          description: Fixture details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Fixture' }
                  meta: { $ref: '#/components/schemas/Meta' }
        '404':
          description: Fixture not found.

  /api/v2/fixtures/{id}/events:
    get:
      summary: Fixture In-Game Events
      description: Retrieve goals, cards, VAR reviews, and substitutions timeline for a match.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string }, description: "Fixture ID (fx_... or integer)" }
        - { name: refresh, in: query, schema: { type: boolean }, description: "Force live refresh" }
      responses:
        '200':
          description: Timeline events array.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/FixtureEvent' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/fixtures/{id}/lineups:
    get:
      summary: Fixture Lineups & Formations
      description: Starting XI, substitutes, formations, and coaches for both teams.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Lineups for home and away team.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/FixtureLineup' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/fixtures/{id}/statistics:
    get:
      summary: Fixture Team Statistics
      description: Possession, shots on target, total passes, corners, fouls, and goalkeeper saves.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Match team statistics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/FixtureStatistic' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/fixtures/{id}/players:
    get:
      summary: Fixture Individual Player Stats
      description: Player ratings, minutes played, passes, tackles, and shots per player.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Player statistics array.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/fixtures/{id}/projection:
    get:
      summary: Match Win/Draw Probabilities (Dixon-Coles v2)
      description: Time-weighted, low-score corrected probability calculations and expected goals.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Match statistical projections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Projection' }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/fixtures/{id}/preview:
    get:
      summary: On-Demand AI Match Preview
      description: Generates or retrieves a grounded match preview using KickoffAPI's local content engine.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: AI preview content.

  /api/v2/fixtures/{id}/content:
    get:
      summary: Stored AI Preview & Post-Match Recap
      description: Pure DB read for pre-generated match previews and post-match recaps.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Match content object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/MatchContent' }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/standings:
    get:
      summary: League Table Standings
      description: Live league standings table including rank, points, goal difference, played, and recent form string.
      parameters:
        - { name: league, in: query, required: true, schema: { type: string }, description: "League ID (lg_... or integer)" }
        - { name: season, in: query, required: true, schema: { type: integer }, description: "Season year (e.g. 2026)" }
      responses:
        '200':
          description: League standings table.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/StandingRow' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/players:
    get:
      summary: List Players
      description: Query players with cursor pagination.
      parameters:
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: List of players.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Player' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/teams/{id}/squad:
    get:
      summary: Team Player Squad
      description: Current active squad rosters (Wikidata CC0 integration).
      parameters:
        - { name: id, in: path, required: true, schema: { type: string }, description: "Team ID (tm_... or integer)" }
      responses:
        '200':
          description: Squad player list.

  /api/v2/teams/{id}/form:
    get:
      summary: Team Recent Form
      description: Recent match performance analytics for a team.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
        - { name: season, in: query, required: true, schema: { type: integer } }
        - { name: n, in: query, schema: { type: integer, default: 5 }, description: "Number of recent matches" }
      responses:
        '200':
          description: Team form data.

  /api/v2/insights/season-sim:
    get:
      summary: League Monte-Carlo Season Simulation
      description: Simulates remaining season fixtures 10,000x to project title, Champions League, and relegation chances.
      parameters:
        - { name: league, in: query, required: true, schema: { type: string } }
        - { name: season, in: query, required: true, schema: { type: integer } }
      responses:
        '200':
          description: Simulation results.

  /api/v2/insights/strength:
    get:
      summary: Team Attack & Defense Strengths
      description: Power ratings per team based on Poisson regression.
      parameters:
        - { name: league, in: query, required: true, schema: { type: string } }
        - { name: season, in: query, required: true, schema: { type: integer } }
      responses:
        '200':
          description: Team attack/defense strength ratings.

  /api/v2/headtohead:
    get:
      summary: Head-to-Head History
      description: Past match records between two teams.
      parameters:
        - { name: team1, in: query, schema: { type: string }, description: "First team ID (tm_... or integer)" }
        - { name: team2, in: query, schema: { type: string }, description: "Second team ID (tm_... or integer)" }
        - { name: h2h, in: query, schema: { type: string }, description: "Combined team string (e.g. tm_1-tm_2 or 33-34)" }
      responses:
        '200':
          description: Head to head match history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Fixture' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/topscorers:
    get:
      summary: Top Scorers Leaderboard
      description: League goalscorers leaderboard.
      parameters:
        - { name: league, in: query, required: true, schema: { type: string } }
        - { name: season, in: query, required: true, schema: { type: integer } }
      responses:
        '200':
          description: Top scorers leaderboard.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/LeaderboardRow' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/topassists:
    get:
      summary: Top Assists Leaderboard
      description: League assist leaders leaderboard.
      parameters:
        - { name: league, in: query, required: true, schema: { type: string } }
        - { name: season, in: query, required: true, schema: { type: integer } }
      responses:
        '200':
          description: Top assists leaderboard.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/LeaderboardRow' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/odds:
    get:
      summary: Fixture Betting Odds
      description: Pre-match odds by bookmaker and bet type.
      parameters:
        - { name: fixture, in: query, required: true, schema: { type: string }, description: "Fixture ID (fx_... or integer)" }
        - { name: bookmaker, in: query, schema: { type: integer }, description: "Filter by bookmaker ID" }
        - { name: bet, in: query, schema: { type: integer }, description: "Filter by bet type ID" }
      responses:
        '200':
          description: Betting odds array.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/OddsRow' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/odds/live:
    get:
      summary: Live In-Play Odds
      description: Real-time odds updates for live matches.
      parameters:
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Live odds data.

  /api/v2/bookmakers:
    get:
      summary: List Bookmakers
      description: Retrieve supported sportsbooks/bookmakers.
      responses:
        '200':
          description: List of bookmakers.

  /api/v2/bet-types:
    get:
      summary: List Bet Types
      description: Retrieve supported betting markets (e.g. Match Winner, Over/Under, Both Teams to Score).
      responses:
        '200':
          description: List of bet types.

  /api/v2/transfers:
    get:
      summary: Player Transfers
      description: Official transfer records by player or team.
      parameters:
        - { name: player, in: query, schema: { type: string }, description: "Player ID (pl_... or integer)" }
        - { name: team, in: query, schema: { type: string }, description: "Team ID (tm_... or integer)" }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Transfer records array.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Transfer' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/injuries:
    get:
      summary: Player Injuries
      description: Player injury reports and absence statuses.
      parameters:
        - { name: fixture, in: query, schema: { type: string } }
        - { name: team, in: query, schema: { type: string } }
        - { name: player, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Injury reports array.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Injury' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/coaches:
    get:
      summary: Team Coaches
      description: Active and historical head coaches for teams.
      parameters:
        - { name: team, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Coach records.

  /api/v2/trophies:
    get:
      summary: Trophies & Honors
      description: Trophy history for players and managers.
      parameters:
        - { name: player, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Trophy history list.

  /api/v2/venues:
    get:
      summary: Venues & Stadiums
      description: Stadium metadata including capacity, city, and photo URL.
      parameters:
        - { name: search, in: query, schema: { type: string }, description: "Stadium name search query" }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: cursor, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Venues list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Venue' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /api/v2/xg:
    get:
      summary: Single Shot xG Model
      description: Evaluates Expected Goals (xG) using KickoffAPI's shot-based model (StatsBomb 120x80 frame).
      parameters:
        - { name: x, in: query, required: true, schema: { type: number }, description: "Pitch x coordinate 0-120 (goal at 120)" }
        - { name: y, in: query, required: true, schema: { type: number }, description: "Pitch y coordinate 0-80 (goal center at 40)" }
        - { name: bodyPart, in: query, schema: { type: string, enum: [Right Foot, Left Foot, Head, Other] } }
        - { name: situation, in: query, schema: { type: string, enum: [Open Play, Free Kick, Penalty, Set Piece] } }
      responses:
        '200':
          description: Calculated xG value and geometric angle/distance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/XgOutput' }
                  meta: { $ref: '#/components/schemas/Meta' }
    post:
      summary: Batch Shot xG Model
      description: Evaluates Expected Goals for an array of shots.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shots:
                  type: array
                  items:
                    type: object
                    properties:
                      x: { type: number }
                      y: { type: number }
                      bodyPart: { type: string }
                      situation: { type: string }
      responses:
        '200':
          description: Batch xG evaluation results.

  /api/v2/xg/model:
    get:
      summary: xG Model Metadata
      description: Returns information about KickoffAPI's trained xG model version, validation metrics, and coordinate frame.
      responses:
        '200':
          description: Model metadata.

  /api/v2/idmap/leagues:
    get:
      summary: Bulk League ID Mapping
      description: Returns mapping table of API-Football legacy integer IDs to KickoffAPI native string IDs (`lg_...`).
      responses:
        '200':
          description: Mapping list.

  /api/v2/resolve:
    get:
      summary: Translate Single Entity ID
      description: Resolves any legacy integer ID to its corresponding native string ID (`koId`).
      parameters:
        - { name: entity, in: query, required: true, schema: { type: string, enum: [league, team, fixture, player] } }
        - { name: legacyId, in: query, required: true, schema: { type: integer } }
      responses:
        '200':
          description: Resolved entity ID object.

  /api/v2/account/status:
    get:
      summary: Account Status & Usage Quota
      description: Returns your current account subscription plan and daily/monthly request usage status.
      responses:
        '200':
          description: Account status and usage quota.