openapi: 3.1.0
info:
  title: NFLMeta API
  version: 1.0.0
  description: |
    Historical NFL data API for games, standings, playoffs, super bowls,
    teams, and metadata timelines.
servers:
  - url: https://nflmeta.org
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Seasons
  - name: Teams
  - name: Games
  - name: Hall of Fame
  - name: Contributors
  - name: Executives
  - name: Standings
  - name: Playoffs
  - name: Super Bowls
  - name: History
  - name: Assets
  - name: Metadata
  - name: Operations
  - name: Usage
paths:
  /api/v1/seasons:
    get:
      tags:
        - Seasons
      summary: List seasons
      operationId: listSeasons
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - name: year_from
          in: query
          schema:
            type: integer
          example: 1990
        - name: year_to
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Seasons list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeasonsListResponse"
              example:
                data:
                  - id: 57
                    year: 2025
                    gameCount: 272
                  - id: 56
                    year: 2024
                    gameCount: 272
                meta:
                  total: 2
                  limit: 50
                  offset: 0
                  returned: 2
                  has_more: false
          headers:
            X-RateLimit-Limit: &a1
              description: Configured monthly quota for this API key
              schema:
                type: integer
            X-RateLimit-Remaining: &a2
              description: Remaining requests in current monthly quota window
              schema:
                type: integer
            X-RateLimit-Reset: &a3
              description: Monthly quota reset timestamp (ISO-8601)
              schema:
                type: string
                format: date-time
            X-RateLimit-Policy: &a4
              description: Quota policy name
              schema:
                type: string
                example: monthly
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/teams:
    get:
      tags:
        - Teams
      summary: List teams
      operationId: listTeams
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - name: search
          in: query
          schema:
            type: string
          example: steelers
        - name: conference
          in: query
          schema:
            type: string
            example: AFC
        - name: division
          in: query
          schema:
            type: string
            example: NORTH
      responses:
        "200":
          description: Teams list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamsListResponse"
              example:
                data:
                  - id: 24
                    abbr: PIT
                    city: Pittsburgh
                    nickname: Steelers
                    fullName: Pittsburgh Steelers
                    conference: AFC
                    division: North
                    gameCount: 1400
                meta:
                  total: 1
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/assets/logos:
    get:
      tags:
        - Assets
      summary: List logo assets
      operationId: listLogoAssets
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum:
              - all
              - team
              - season
              - super_bowl
              - stadium
            default: all
          example: team
        - name: search
          in: query
          schema:
            type: string
          example: steelers
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Logo assets
          content:
            application/json:
              example:
                data:
                  - id: team-pit
                    category: team
                    key: PIT
                    label: Pittsburgh Steelers
                    url: https://nflmeta.org/hero_main/logos/pittsburgh-steelers-logo-transparent.png
                    source: local
                meta:
                  total: 32
                  limit: 100
                  offset: 0
                  returned: 1
                  has_more: false
                  categories:
                    - all
                    - team
                    - season
                    - super_bowl
                    - stadium
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/assets/images:
    get:
      tags:
        - Assets
      summary: List curated image assets
      operationId: listImageAssets
      parameters:
        - name: group
          in: query
          schema:
            type: string
            enum:
              - all
              - brand
              - players
            default: all
          example: brand
        - name: search
          in: query
          schema:
            type: string
          example: logo
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Curated image assets
          content:
            application/json:
              example:
                data:
                  - id: brand-nflmeta-logo
                    group: brand
                    key: nflmeta_logo
                    label: NFLMeta Logo
                    url: https://nflmeta.org/hero_main/NFLMeta_Logo.png
                    source: local
                meta:
                  total: 11
                  limit: 100
                  offset: 0
                  returned: 1
                  has_more: false
                  groups:
                    - all
                    - brand
                    - players
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/teams/{abbr}:
    get:
      tags:
        - Teams
      summary: Team profile snapshot
      operationId: getTeam
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Team profile
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/TeamProfile"
              example:
                data:
                  team:
                    id: 24
                    abbr: PIT
                    city: Pittsburgh
                    nickname: Steelers
                    fullName: Pittsburgh Steelers
                    conference: AFC
                    division: North
                    gameCount: 1400
                  seasonYear: 2025
                  seasonYears:
                    - 2025
                    - 2024
                    - 2023
                  displayName: Pittsburgh Steelers
                  record:
                    wins: 10
                    losses: 7
                    ties: 0
                    gamesPlayed: 17
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/games:
    get:
      tags:
        - Teams
      summary: Team recent games
      operationId: getTeamRecentGames
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 5
          example: 3
      responses:
        "200":
          description: Team recent games
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/GameListItem"
                  meta:
                    type: object
                    properties:
                      team:
                        type: string
                      returned:
                        type: integer
                      limit:
                        type: integer
              example:
                data:
                  - id: 12345
                    isPlayoff: false
                    seasonYear: 2025
                    week: 17
                    round: null
                    gameDate: 2026-01-04
                    kickoffAt: 2026-01-04T13:00:00-05:00
                    awayAbbr: PIT
                    awayName: Pittsburgh Steelers
                    homeAbbr: CIN
                    homeName: Cincinnati Bengals
                    awayScore: 24
                    homeScore: 20
                    broadcastNetwork: CBS
                    stadium: Paycor Stadium
                meta:
                  team: PIT
                  returned: 1
                  limit: 3
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/profile:
    get:
      tags:
        - Teams
      summary: Team profile with extras
      operationId: getTeamProfile
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Team profile plus extras
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    allOf:
                      - $ref: "#/components/schemas/TeamProfile"
                      - type: object
                        properties:
                          extras:
                            $ref: "#/components/schemas/TeamProfileExtras"
              example:
                data:
                  team:
                    id: 24
                    abbr: PIT
                    city: Pittsburgh
                    nickname: Steelers
                    fullName: Pittsburgh Steelers
                    conference: AFC
                    division: North
                    gameCount: 1400
                  seasonYear: 2025
                  seasonYears:
                    - 2025
                    - 2024
                    - 2023
                  displayName: Pittsburgh Steelers
                  record:
                    wins: 10
                    losses: 7
                    ties: 0
                    gamesPlayed: 17
                  extras:
                    offense:
                      - label: Yards per Play
                        value: "5.4"
                    defense:
                      - label: Points Allowed/G
                        value: "19.1"
                    specialTeams:
                      - label: FG%
                        value: "88.2"
                    powerRankings:
                      - source: NFLMeta
                        rank: 8
                        sourceUrl: null
                        updatedAt: 2026-01-10
                    stadium:
                      name: Acrisure Stadium
                      location: Pittsburgh, PA
                      capacity: 68400
                      surface: Grass
                      inauguralDate: 2001-08-18
                      logoUrl: https://nflmeta.org/assets/stadiums/acrisure.png
                    proBowl: []
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/profile/{field}:
    get:
      tags:
        - Teams
      summary: Get one team profile field
      description: Returns a single top-level field from the full team profile payload.
      operationId: getTeamProfileField
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: extras
      responses:
        "200":
          description: Team profile field value
          content:
            application/json:
              example:
                data:
                  field: extras
                  value:
                    powerRankings: []
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/identity:
    get:
      tags:
        - Teams
      summary: Team identity slice
      description: Returns a smaller team identity payload with canonical team fields and available season years.
      operationId: getTeamIdentity
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
      responses:
        "200":
          description: Team identity
          content:
            application/json:
              example:
                data:
                  id: 24
                  abbr: PIT
                  city: Pittsburgh
                  nickname: Steelers
                  fullName: Pittsburgh Steelers
                  conference: AFC
                  division: North
                  gameCount: 0
                  seasonYears: [2025, 2024, 2023]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/identity/{field}:
    get:
      tags:
        - Teams
      summary: Get one team identity field
      description: Returns a single field from the team identity slice. Supported fields include id, abbr, city, nickname, fullName, conference, division, gameCount, and seasonYears.
      operationId: getTeamIdentityField
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: city
      responses:
        "200":
          description: Team identity field value
          content:
            application/json:
              example:
                data:
                  field: city
                  value: Pittsburgh
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/season:
    get:
      tags:
        - Teams
      summary: Team season slice
      description: Returns only the season-specific profile fields for one team, without extras.
      operationId: getTeamSeasonSlice
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Team season slice
          content:
            application/json:
              example:
                data:
                  season_year: 2025
                  season_years: [2025, 2024, 2023]
                  display_name: Pittsburgh Steelers
                  record:
                    wins: 10
                    losses: 7
                    ties: 0
                    gamesPlayed: 17
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/season/{field}:
    get:
      tags:
        - Teams
      summary: Get one team season field
      description: Returns a single field from the team season slice.
      operationId: getTeamSeasonField
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: record
      responses:
        "200":
          description: Team season field value
          content:
            application/json:
              example:
                data:
                  field: record
                  value:
                    wins: 10
                    losses: 7
                    ties: 0
                    gamesPlayed: 17
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/stats:
    get:
      tags:
        - Teams
      summary: Team stats slice
      description: Returns only the offense, defense, and special teams stat groups for one team season.
      operationId: getTeamStatsSlice
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Team stat groups
          content:
            application/json:
              example:
                data:
                  season_year: 2025
                  offense:
                    - label: Yards per Play
                      value: "5.4"
                  defense:
                    - label: Points Allowed/G
                      value: "19.1"
                  special_teams:
                    - label: FG%
                      value: "88.2"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/stats/{field}:
    get:
      tags:
        - Teams
      summary: Get one team stats field
      description: Returns a single field from the team stats slice.
      operationId: getTeamStatsField
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: offense
      responses:
        "200":
          description: Team stats field value
          content:
            application/json:
              example:
                data:
                  field: offense
                  value:
                    - label: Yards per Play
                      value: "5.4"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/power-rankings:
    get:
      tags:
        - Teams
      summary: Team power rankings slice
      description: Returns only power ranking rows for one team season.
      operationId: getTeamPowerRankingsSlice
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Team power rankings
          content:
            application/json:
              example:
                data:
                  season_year: 2025
                  power_rankings:
                    - source: NFLMeta
                      rank: 8
                      sourceUrl: null
                      updatedAt: 2026-01-10
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/power-rankings/{field}:
    get:
      tags:
        - Teams
      summary: Get one team power rankings field
      description: Returns a single field from the team power rankings slice.
      operationId: getTeamPowerRankingsField
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: power_rankings
      responses:
        "200":
          description: Team power rankings field value
          content:
            application/json:
              example:
                data:
                  field: power_rankings
                  value:
                    - source: NFLMeta
                      rank: 8
                      sourceUrl: null
                      updatedAt: 2026-01-10
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/stadium:
    get:
      tags:
        - Teams
      summary: Team stadium slice
      description: Returns only the resolved stadium payload for one team season.
      operationId: getTeamStadiumSlice
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Team stadium
          content:
            application/json:
              example:
                data:
                  season_year: 2025
                  stadium:
                    name: Acrisure Stadium
                    location: Pittsburgh, PA
                    capacity: 68400
                    surface: Grass
                    inauguralDate: 2001-08-18
                    logoUrl: https://nflmeta.org/assets/nfl_stadiums/acrisure.png
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/stadium/{field}:
    get:
      tags:
        - Teams
      summary: Get one team stadium field
      description: Returns a single field from the team stadium slice.
      operationId: getTeamStadiumField
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: stadium
      responses:
        "200":
          description: Team stadium field value
          content:
            application/json:
              example:
                data:
                  field: stadium
                  value:
                    name: Acrisure Stadium
                    location: Pittsburgh, PA
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/pro-bowl:
    get:
      tags:
        - Teams
      summary: Team Pro Bowl slice
      description: Returns only the resolved Pro Bowl roster for one team season.
      operationId: getTeamProBowlSlice
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Team Pro Bowl roster
          content:
            application/json:
              example:
                data:
                  season_year: 2025
                  pro_bowl:
                    - playerKey: gsis:00-0034857
                      name: Josh Allen
                      position: QB
                      isReplacement: false
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/teams/{abbr}/pro-bowl/{field}:
    get:
      tags:
        - Teams
      summary: Get one team Pro Bowl field
      description: Returns a single field from the team Pro Bowl slice.
      operationId: getTeamProBowlField
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: pro_bowl
      responses:
        "200":
          description: Team Pro Bowl field value
          content:
            application/json:
              example:
                data:
                  field: pro_bowl
                  value:
                    - playerKey: gsis:00-0034857
                      name: Josh Allen
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/games:
    get:
      tags:
        - Players
      summary: Get player game logs
      description: Returns game-by-game stat lines for one player. Use season and week filters for granular lookups like a quarterback's passing yards, touchdowns, and interceptions in a specific week.
      operationId: getPlayerGameLogs
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season
          in: query
          description: NFL season year to filter on.
          schema:
            type: integer
          example: 2025
        - name: week
          in: query
          description: Week number within the selected season.
          schema:
            type: integer
          example: 3
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Player game logs
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  meta:
                    type: object
              example:
                data:
                  - game:
                      id: 305
                      seasonYear: 2025
                      week: 3
                      gameDate: 2025-09-18
                      teamAbbr: BUF
                      teamName: Buffalo Bills
                      opponentAbbr: MIA
                      opponentName: Miami Dolphins
                      homeAway: home
                      teamScore: 31
                      opponentScore: 21
                      result: W
                    passing:
                      completions: 22
                      attempts: 28
                      yards: 213
                      touchdowns: 3
                      interceptions: 0
                      sacks: 2
                      sackYards: 10
                      long: 30
                      rating: 134.1
                    rushing:
                      attempts: 4
                      yards: 25
                      touchdowns: 0
                      long: 19
                    receiving:
                      targets: 0
                      receptions: 0
                      yards: 0
                      touchdowns: 0
                      long: 0
                    fumbles:
                      fumbles: 1
                      lost: 0
                    defense:
                      interceptions: 0
                      interceptionYards: 0
                      sacks: 0
                      tacklesCombined: 0
                      tacklesSolo: 0
                      tacklesAssists: 0
                      forcedFumbles: 0
                      fumbleRecoveries: 1
                    returns: null
                    kicking: null
                meta:
                  player:
                    playerKey: gsis:00-0034857
                    displayName: Josh Allen
                  season: 2025
                  week: 3
                  limit: 20
                  offset: 0
                  returned: 1
                  total: 1
                  has_more: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/career:
    get:
      tags:
        - Players
      summary: Get player career totals
      description: Returns the persisted normalized career totals row for one player from `player_career_stats`, including core totals plus expanded snap, advanced, explosive-play, and specialist fields when present.
      operationId: getPlayerCareerTotals
      parameters:
        - $ref: "#/components/parameters/playerKey"
      responses:
        "200":
          description: Player career totals
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
              example:
                data:
                  player_id: 2543
                  player_key: gsis:00-0027793
                  display_name: Antonio Brown
                  stat_coverage_start_season: 2010
                  stat_coverage_end_season: 2021
                  seasons_with_stats: 15
                  tracked_stat_games: 159
                  pass_yds: 35
                  pass_passer_rating: 39.583
                  rush_yds: 168
                  rush_long: 16
                  rec: 928
                  rec_yds: 13209
                  rec_long: 71
                  rec_td: 88
                  rec_20_plus: 169
                  off_snaps: 9257
                  rec_yac: 4903
                  def_sacks: 0.0
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/career/{field}:
    get:
      tags:
        - Players
      summary: Get one player career field
      description: Returns a single field from the player career totals payload.
      operationId: getPlayerCareerField
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: pass_passer_rating
      responses:
        "200":
          description: Player career field value
          content:
            application/json:
              example:
                data:
                  field: pass_passer_rating
                  value: 99.4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/career/seasons:
    get:
      tags:
        - Players
      summary: Get player season-by-season career stats
      description: Returns persisted normalized season rows from `player_career_stat_seasons` for one player, including core stat totals plus expanded snap, advanced, explosive-play, and specialist columns.
      operationId: getPlayerCareerSeasons
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season_type
          in: query
          description: Filter by season type.
          schema:
            type: string
            enum: [REG, POST]
          example: REG
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Player career stat seasons
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  meta:
                    type: object
              example:
                data:
                  - season_year: 2017
                    season_type: REG
                    season_team_abbr: PIT
                    rec: 101
                    rec_yds: 1533
                    rec_td: 9
                    targets: 163
                    rec_long: 51
                    rec_20_plus: 24
                    off_snaps: 909
                  - season_year: 2016
                    season_type: REG
                    season_team_abbr: PIT
                    rec: 106
                    rec_yds: 1284
                    rec_td: 12
                    targets: 154
                    rec_long: 51
                    rec_yac: 450
                meta:
                  total: 15
                  limit: 50
                  offset: 0
                  returned: 2
                  has_more: false
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/kicking:
    get:
      tags:
        - Players
      summary: Get player kicking season rows
      description: Returns season-level kicking rows from `player_kicker_season_stats` for one player. Use the season and field drilldowns when the client only needs one season or one stat.
      operationId: getPlayerKickingSeasons
      parameters:
        - $ref: "#/components/parameters/playerKey"
      responses:
        "200":
          description: Player kicking seasons
          content:
            application/json:
              example:
                data:
                  - season_year: 2025
                    season_type: REG
                    team_abbr: PIT
                    row_scope: TEAM
                    fgm_total: 27
                    fga_total: 32
                    xpm: 42
                    xpa: 43
                    fg_long: 60
                    fg_pct: 84.4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/kicking/{season_year}:
    get:
      tags:
        - Players
      summary: Get one player kicking season row
      description: Returns one season-level kicking row for a player.
      operationId: getPlayerKickingSeason
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season_year
          in: path
          required: true
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Player kicking season
          content:
            application/json:
              example:
                data:
                  season_year: 2025
                  season_type: REG
                  team_abbr: PIT
                  row_scope: TEAM
                  fga_20_29: 6
                  fgm_20_29: 6
                  fga_total: 32
                  fgm_total: 27
                  fg_long: 60
                  xpm: 42
                  xpa: 43
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/kicking/{season_year}/{field}:
    get:
      tags:
        - Players
      summary: Get one player kicking season field
      description: Returns one top-level field from a player's season-level kicking row.
      operationId: getPlayerKickingSeasonField
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season_year
          in: path
          required: true
          schema:
            type: integer
          example: 2025
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: fgm_total
      responses:
        "200":
          description: Player kicking season field value
          content:
            application/json:
              example:
                data:
                  field: fgm_total
                  value: 27
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/punting:
    get:
      tags:
        - Players
      summary: Get player punting season rows
      description: Returns season-level punting rows from `player_punter_season_stats` for one player. Use the season and field drilldowns when the client only needs one season or one stat.
      operationId: getPlayerPuntingSeasons
      parameters:
        - $ref: "#/components/parameters/playerKey"
      responses:
        "200":
          description: Player punting seasons
          content:
            application/json:
              example:
                data:
                  - season_year: 2025
                    season_type: REG
                    team_abbr: CLE
                    row_scope: TEAM
                    punts: 91
                    punt_yards: 4165
                    punt_avg: 45.8
                    net_avg: 37.0
                    punts_inside_20: 23
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/punting/{season_year}:
    get:
      tags:
        - Players
      summary: Get one player punting season row
      description: Returns one season-level punting row for a player.
      operationId: getPlayerPuntingSeason
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season_year
          in: path
          required: true
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Player punting season
          content:
            application/json:
              example:
                data:
                  season_year: 2025
                  season_type: REG
                  team_abbr: CLE
                  row_scope: TEAM
                  punts: 91
                  punt_yards: 4165
                  punt_avg: 45.8
                  net_yards: 3443
                  net_avg: 37.0
                  punt_long: 67
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/punting/{season_year}/{field}:
    get:
      tags:
        - Players
      summary: Get one player punting season field
      description: Returns one top-level field from a player's season-level punting row.
      operationId: getPlayerPuntingSeasonField
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season_year
          in: path
          required: true
          schema:
            type: integer
          example: 2025
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: net_avg
      responses:
        "200":
          description: Player punting season field value
          content:
            application/json:
              example:
                data:
                  field: net_avg
                  value: 37
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/identity:
    get:
      tags:
        - Players
      summary: Get player identity slice
      description: Returns a smaller identity-focused player payload with name, team, position, status, and hero-card fields.
      operationId: getPlayerIdentity
      parameters:
        - $ref: "#/components/parameters/playerKey"
      responses:
        "200":
          description: Player identity slice
          content:
            application/json:
              example:
                data:
                  player_key: gsis:00-0034857
                  display_name: Josh Allen
                  football_name: Josh Allen
                  first_name: Josh
                  last_name: Allen
                  position_group: QB
                  position: QB
                  latest_team_abbr: BUF
                  jersey_number: "17"
                  rookie_season: 2018
                  last_season: 2025
                  status: ACT
                  years_of_experience: 8
                  headshot_url: /media/player-headshots/manual/gsis_00-0034857-example.webp
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/identity/{field}:
    get:
      tags:
        - Players
      summary: Get one player identity field
      description: Returns a single field from the player identity slice. Supported fields include player_key, display_name, football_name, first_name, last_name, position_group, position, latest_team_abbr, jersey_number, rookie_season, last_season, status, years_of_experience, and headshot_url.
      operationId: getPlayerIdentityField
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: display_name
      responses:
        "200":
          description: Player identity field value
          content:
            application/json:
              example:
                data:
                  field: display_name
                  value: Josh Allen
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/bio:
    get:
      tags:
        - Players
      summary: Get player bio slice
      description: Returns a smaller bio-focused player payload with birth, size, college, and draft fields.
      operationId: getPlayerBio
      parameters:
        - $ref: "#/components/parameters/playerKey"
      responses:
        "200":
          description: Player bio slice
          content:
            application/json:
              example:
                data:
                  birth_date: 1996-05-21
                  birth_place: Firebaugh, California
                  height_in: 77
                  weight_lb: 237
                  college_name: Wyoming
                  college_conference: Mountain West
                  draft_year: 2018
                  draft_round: 1
                  draft_pick: 7
                  draft_team: BUF
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/bio/{field}:
    get:
      tags:
        - Players
      summary: Get one player bio field
      description: Returns a single field from the player bio slice.
      operationId: getPlayerBioField
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: birth_place
      responses:
        "200":
          description: Player bio field value
          content:
            application/json:
              example:
                data:
                  field: birth_place
                  value: Firebaugh, California
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/ids:
    get:
      tags:
        - Players
      summary: Get player external ids
      description: Returns canonical external ids for a single player.
      operationId: getPlayerIds
      parameters:
        - $ref: "#/components/parameters/playerKey"
      responses:
        "200":
          description: Player ids
          content:
            application/json:
              example:
                data:
                  player_key: gsis:00-0034857
                  gsis_id: 00-0034857
                  nfl_id: "2560757"
                  pfr_id: AlleJo02
                  espn_id: "3918298"
                  pff_id: "11765"
                  otc_id: null
                  smart_id: null
                  esb_id: null
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/ids/{field}:
    get:
      tags:
        - Players
      summary: Get one player id field
      description: Returns a single field from the player ids slice.
      operationId: getPlayerIdsField
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: pfr_id
      responses:
        "200":
          description: Player id field value
          content:
            application/json:
              example:
                data:
                  field: pfr_id
                  value: AlleJo02
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/roster:
    get:
      tags:
        - Players
      summary: Get player roster history slice
      description: Returns only roster-history rows for one player.
      operationId: getPlayerRosterHistory
      parameters:
        - $ref: "#/components/parameters/playerKey"
      responses:
        "200":
          description: Player roster history
          content:
            application/json:
              example:
                data:
                  - season_year: 2025
                    source_team_abbr: BUF
                    jersey_number: "17"
                    status: ACT
                    status_description_abbr: ACT
                    week: 18
                    game_type: REG
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/honors:
    get:
      tags:
        - Players
      summary: Get player honors slice
      description: Returns only player honors data, split into Pro Bowls, All-Pro selections, awards, and Hall of Fame status.
      operationId: getPlayerHonors
      parameters:
        - $ref: "#/components/parameters/playerKey"
      responses:
        "200":
          description: Player honors
          content:
            application/json:
              example:
                data:
                  pro_bowls:
                    - season_year: 2024
                      is_replacement: false
                  all_pros:
                    - season_year: 2024
                      selector_name: Associated Press
                      team_level: 1
                      position: QB
                  awards:
                    - award_key: nfl_player_of_the_week
                      award_name: NFL Player of the Week
                      season_year: 2024
                  hall_of_fame: null
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/honors/{field}:
    get:
      tags:
        - Players
      summary: Get one player honors field
      description: Returns a single field from the player honors slice.
      operationId: getPlayerHonorsField
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: pro_bowls
      responses:
        "200":
          description: Player honors field value
          content:
            application/json:
              example:
                data:
                  field: pro_bowls
                  value:
                    - season_year: 2024
                      is_replacement: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/splits:
    get:
      tags:
        - Players
      summary: Get player game splits
      description: Returns aggregated game-log totals for one player with split buckets for season type, team, opponent, home/away, and result.
      operationId: getPlayerSplits
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season
          in: query
          description: Restrict splits to one season year.
          schema:
            type: integer
          example: 2024
        - name: season_type
          in: query
          description: Filter by season type.
          schema:
            type: string
            enum: [REG, POST, ALL]
            default: ALL
          example: ALL
      responses:
        "200":
          description: Player split totals
          content:
            application/json:
              example:
                data:
                  player:
                    id: 2506109
                    playerKey: gsis:00-0037834
                    displayName: Saquon Barkley
                  season: 2024
                  seasonType: ALL
                  totals:
                    games: 20
                    rush_yds: 2283
                    rush_td: 15
                    rec_yds: 348
                  by_season_type:
                    - season_type: POST
                      games: 4
                      rush_yds: 499
                  by_team:
                    - team_abbr: PHI
                      games: 20
                      rush_yds: 2283
                  by_home_away:
                    - home_away: home
                      games: 10
                      rush_yds: 1127
                  by_result:
                    - result: W
                      games: 15
                      rush_yds: 1810
                  by_opponent:
                    - opponent_abbr: WAS
                      games: 3
                      rush_yds: 421
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/splits/{field}:
    get:
      tags:
        - Players
      summary: Get one player splits field
      description: Returns a single top-level field from the player splits payload.
      operationId: getPlayerSplitsField
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season
          in: query
          schema:
            type: integer
          example: 2024
        - name: season_type
          in: query
          schema:
            type: string
            enum: [REG, POST, ALL]
            default: ALL
          example: ALL
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: totals
      responses:
        "200":
          description: Player splits field value
          content:
            application/json:
              example:
                data:
                  field: totals
                  value:
                    games: 17
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/records:
    get:
      tags:
        - Players
      summary: Get player best game and season records
      description: Returns career total, best season, and best game snapshots for a configurable list of stats.
      operationId: getPlayerRecords
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season_type
          in: query
          description: Filter the game-record search by season type.
          schema:
            type: string
            enum: [REG, POST, ALL]
            default: ALL
          example: ALL
        - name: stats
          in: query
          description: Comma-separated stat list. Defaults to a curated cross-position record set.
          schema:
            type: string
          example: pass_yds,pass_td,rush_yds
      responses:
        "200":
          description: Player records
          content:
            application/json:
              example:
                data:
                  career:
                    player_key: gsis:00-0034857
                    display_name: Josh Allen
                    pass_yds: 26434
                    pass_td: 195
                  records:
                    - stat: pass_yds
                      family: passing
                      career_total: 26434
                      best_season:
                        value: 4544
                        season_year: 2020
                        season_type: REG
                        team_abbr: BUF
                      best_game:
                        value: 424
                        game_id: 79589
                        season_year: 2020
                        season_type: REG
                        week: 17
                        opponent_abbr: MIA
                        stat_snapshot:
                          pass_yds: 424
                          pass_td: 4
                    - stat: pass_td
                      family: passing
                      career_total: 195
                      best_season:
                        value: 37
                        season_year: 2020
                        season_type: REG
                        team_abbr: BUF
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/players/{player_key}/records/{field}:
    get:
      tags:
        - Players
      summary: Get one player records field
      description: Returns a single top-level field from the player records payload.
      operationId: getPlayerRecordsField
      parameters:
        - $ref: "#/components/parameters/playerKey"
        - name: season_type
          in: query
          schema:
            type: string
            enum: [REG, POST, ALL]
            default: ALL
          example: ALL
        - name: stats
          in: query
          schema:
            type: string
          example: pass_yds,pass_td
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: records
      responses:
        "200":
          description: Player records field value
          content:
            application/json:
              example:
                data:
                  field: records
                  value:
                    - stat: pass_yds
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/stats/players/catalog:
    get:
      tags:
        - Stats
      summary: Discover player stats query fields
      description: Returns the live supported stat columns and filter names for the player season and career stats query endpoints. Use this instead of hardcoding stat allowlists.
      operationId: getPlayerStatsCatalog
      responses:
        "200":
          description: Player stats catalog
          content:
            application/json:
              example:
                data:
                  season_stats: [rush_yds, rec_yds, def_sacks, off_snaps, pass_passer_rating, rec_avg_separation, rush_yards_over_expected, fg_made_40_49, punt_avg, pass_20_plus]
                  career_stats: [rush_yds, rec_yds, def_sacks, tracked_stat_games, def_pressures, pass_passer_rating, rec_avg_cushion, rush_expected_yards, kick_points, fg_long]
                  game_stats: [pass_yds, rush_yds, rec_yds, def_sacks, pass_cmp_pct]
                  season_filters: [season_year, season_type, team, position, position_group, season_position, season_position_group, depth_chart_position, min_games, min_starts, min_pass_att, min_rush_att, min_targets, min_rec, min_fga, min_punts, search, min_value, max_value, order, limit, offset]
                  career_filters: [team, position, position_group, position_mode, min_games, min_starts, min_pass_att, min_rush_att, min_targets, min_rec, min_fga, min_punts, search, min_value, max_value, order, limit, offset]
                  game_filters: [season_year, season_type, week, week_from, week_to, team, opponent, home_away, result, position, search, min_pass_att, min_rush_att, min_targets, min_rec, min_fga, min_punts, min_value, max_value, order, limit, offset]
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/seasons:
    get:
      tags:
        - Stats
      summary: Query cross-player season stat leaderboards
      description: Returns player season rows across the whole database, filtered by season and ranked by the requested stat column. Supports raw totals plus normalized snap, advanced, explosive-play, and specialist fields. Season team and season position fields reflect the historical season row, not the player's current profile. Use `/api/v1/stats/players/catalog` for the live stat allowlist.
      operationId: listPlayerSeasonStatLeaders
      parameters:
        - name: season_year
          in: query
          required: true
          description: Season year to query.
          schema:
            type: integer
          example: 2024
        - name: stat
          in: query
          required: true
          description: Stat column to rank by. Use `/api/v1/stats/players/catalog` for the current allowlist.
          schema:
            type: string
          example: pass_passer_rating
        - name: season_type
          in: query
          description: Filter by season type.
          schema:
            type: string
            enum: [REG, POST]
          example: REG
        - name: team
          in: query
          description: Filter by team abbreviation for the stored season row.
          schema:
            type: string
          example: PHI
        - name: position
          in: query
          description: Filter by canonical player position.
          schema:
            type: string
          example: RB
        - name: position_group
          in: query
          description: Filter by canonical player position group.
          schema:
            type: string
          example: RB
        - name: season_position
          in: query
          description: Filter by the stored historical season position for that row.
          schema:
            type: string
          example: OLB
        - name: season_position_group
          in: query
          description: Filter by the stored historical season position group for that row.
          schema:
            type: string
          example: LB
        - name: depth_chart_position
          in: query
          description: Filter by the stored historical depth chart position for that season row.
          schema:
            type: string
          example: ROLB
        - name: min_games
          in: query
          description: Minimum season games with tracked stats.
          schema:
            type: integer
          example: 10
        - name: min_pass_att
          in: query
          description: Minimum passing attempts qualification filter.
          schema:
            type: integer
          example: 200
        - name: min_rush_att
          in: query
          description: Minimum rushing attempts qualification filter.
          schema:
            type: integer
          example: 100
        - name: min_targets
          in: query
          description: Minimum targets qualification filter.
          schema:
            type: integer
          example: 75
        - name: search
          in: query
          description: Case-insensitive player search against display and key fields.
          schema:
            type: string
          example: barkley
        - name: min_value
          in: query
          description: Minimum stat value to include.
          schema:
            type: number
          example: 1000
        - name: max_value
          in: query
          description: Maximum stat value to include.
          schema:
            type: number
          example: 2500
        - name: order
          in: query
          description: Sort direction for the selected stat.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Cross-player season stat results
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  meta:
                    type: object
              example:
                data:
                  - rank: 1
                    player_key: gsis:00-0034857
                    display_name: Josh Allen
                    position: QB
                    season_position: QB
                    season_position_group: QB
                    season_team_abbr: BUF
                    latest_team_abbr: BUF
                    season_year: 2024
                    season_type: REG
                    stat_value: 101.423
                    pass_passer_rating: 101.423
                  - rank: 2
                    player_key: gsis:00-0036404
                    display_name: Lamar Jackson
                    position: QB
                    season_position: QB
                    season_position_group: QB
                    season_team_abbr: BAL
                    latest_team_abbr: BAL
                    season_year: 2024
                    season_type: REG
                    stat_value: 98.734
                    pass_passer_rating: 98.734
                meta:
                  total: 2
                  limit: 50
                  offset: 0
                  returned: 2
                  has_more: false
                  season_year: 2024
                  season_type: REG
                  stat: pass_passer_rating
                  order: desc
                  filters:
                    team: null
                    position: QB
                    position_group: null
                    season_position: QB
                    season_position_group: null
                    depth_chart_position: null
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/seasons/{season_year}/{stat}:
    get:
      tags:
        - Stats
      summary: Query one season stat leaderboard by path
      description: Path-based shortcut for cross-player season leaderboards. Equivalent to `/api/v1/stats/players/seasons?season_year=...&stat=...` with both values encoded in the route.
      operationId: listPlayerSeasonStatLeadersByPath
      parameters:
        - name: season_year
          in: path
          required: true
          schema:
            type: integer
          example: 2024
        - name: stat
          in: path
          required: true
          schema:
            type: string
          example: rush_yds
        - name: season_type
          in: query
          schema:
            type: string
            enum: [REG, POST]
          example: REG
        - name: team
          in: query
          schema:
            type: string
          example: BAL
        - name: position
          in: query
          schema:
            type: string
          example: RB
        - name: order
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Season stat leaderboard
          content:
            application/json:
              example:
                data:
                  - rank: 1
                    player_key: gsis:00-0034796
                    display_name: Derrick Henry
                    season_year: 2024
                    season_type: REG
                    stat_value: 1921
                    rush_yds: 1921
                meta:
                  season_year: 2024
                  stat: rush_yds
                  order: desc
                  limit: 50
                  offset: 0
                  returned: 1
                  total: 1
                  has_more: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/careers:
    get:
      tags:
        - Stats
      summary: Query cross-player career total leaderboards
      description: Returns player career total rows across the whole database, ranked by the requested stat column. Supports raw totals plus normalized snap, advanced, explosive-play, and specialist fields. Position filters use season-derived historical career metadata from `player_career_stats`. Use `/api/v1/stats/players/catalog` for the live stat allowlist.
      operationId: listPlayerCareerStatLeaders
      parameters:
        - name: stat
          in: query
          required: true
          description: Career stat column to rank by. Use `/api/v1/stats/players/catalog` for the current allowlist.
          schema:
            type: string
          example: def_pressures
        - name: team
          in: query
          description: Filter by latest team abbreviation in the career totals table.
          schema:
            type: string
          example: PIT
        - name: position
          in: query
          description: Filter by season-derived career position.
          schema:
            type: string
          example: OLB
        - name: position_group
          in: query
          description: Filter by season-derived career position group.
          schema:
            type: string
          example: DEF
        - name: position_mode
          in: query
          description: Match any historical career position or only the derived primary career position.
          schema:
            type: string
            enum: [any, primary]
            default: any
          example: any
        - name: min_games
          in: query
          description: Minimum tracked games qualification filter.
          schema:
            type: integer
          example: 50
        - name: min_pass_att
          in: query
          description: Minimum passing attempts qualification filter.
          schema:
            type: integer
          example: 1000
        - name: search
          in: query
          description: Case-insensitive player search against display and key fields.
          schema:
            type: string
          example: watt
        - name: min_value
          in: query
          description: Minimum stat value to include.
          schema:
            type: number
          example: 100
        - name: max_value
          in: query
          description: Maximum stat value to include.
          schema:
            type: number
          example: 200
        - name: order
          in: query
          description: Sort direction for the selected stat.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Cross-player career stat results
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  meta:
                    type: object
              example:
                data:
                  - rank: 1
                    player_key: gsis:00-0033873
                    display_name: Patrick Mahomes
                    position: QB
                    career_positions: [QB]
                    latest_team_abbr: KC
                    stat_coverage_start_season: 2017
                    stat_coverage_end_season: 2025
                    stat_value: 103.417
                    pass_passer_rating: 103.417
                  - rank: 2
                    player_key: gsis:00-0036404
                    display_name: Lamar Jackson
                    position: QB
                    career_positions: [QB]
                    latest_team_abbr: BAL
                    stat_coverage_start_season: 2018
                    stat_coverage_end_season: 2025
                    stat_value: 101.284
                    pass_passer_rating: 101.284
                meta:
                  total: 2
                  limit: 50
                  offset: 0
                  returned: 2
                  has_more: false
                  stat: pass_passer_rating
                  order: desc
                  position_mode: any
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/careers/{stat}:
    get:
      tags:
        - Stats
      summary: Query one career stat leaderboard by path
      description: Path-based shortcut for cross-player career leaderboards. Equivalent to `/api/v1/stats/players/careers?stat=...` with the stat encoded in the route.
      operationId: listPlayerCareerStatLeadersByPath
      parameters:
        - name: stat
          in: path
          required: true
          description: Career stat column to rank by.
          schema:
            type: string
          example: pass_passer_rating
        - name: team
          in: query
          schema:
            type: string
          example: KC
        - name: position
          in: query
          schema:
            type: string
          example: QB
        - name: order
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Career stat leaderboard
          content:
            application/json:
              example:
                data:
                  - rank: 1
                    player_key: gsis:00-0033873
                    display_name: Patrick Mahomes
                    stat_value: 103.417
                    pass_passer_rating: 103.417
                meta:
                  stat: pass_passer_rating
                  order: desc
                  limit: 50
                  offset: 0
                  returned: 1
                  total: 1
                  has_more: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/games:
    get:
      tags:
        - Stats
      summary: Query cross-player game stat logs
      description: Returns player game rows across the database, ranked by the requested game stat column. Supports `season_type=REG|POST|ALL` plus team, opponent, home/away, result, and week-range split filters. Regular-season rows use PFR boxscore data; postseason rows use the structured playoff stat tables.
      operationId: listPlayerGameStatLeaders
      parameters:
        - name: season_year
          in: query
          required: true
          schema:
            type: integer
          example: 2024
        - name: stat
          in: query
          required: true
          schema:
            type: string
            enum: [pass_cmp, pass_att, pass_yds, pass_td, pass_int, pass_sacks, pass_sack_yds_lost, rush_att, rush_yds, rush_td, targets, rec, rec_yds, rec_td, fumbles, fumbles_lost, def_int, def_int_yds, def_sacks, def_tkl_combined, def_tkl_solo, def_tkl_ast, def_ff, def_fr, kick_returns, kick_return_yds, punt_returns, punt_return_yds, fgm, fga, xpm, xpa, punts, punt_yds, catch_pct, fg_pct, pass_cmp_pct, pass_td_pct, pass_yds_per_att, punt_yds_per_punt, rec_yds_per_rec, rush_yds_per_att, xp_pct]
          example: pass_yds
        - name: season_type
          in: query
          schema:
            type: string
            enum: [REG, POST, ALL]
            default: REG
          example: ALL
        - name: week
          in: query
          schema:
            type: integer
          example: 3
        - name: week_from
          in: query
          schema:
            type: integer
          example: 1
        - name: week_to
          in: query
          schema:
            type: integer
          example: 4
        - name: team
          in: query
          schema:
            type: string
          example: BUF
        - name: opponent
          in: query
          schema:
            type: string
          example: MIA
        - name: home_away
          in: query
          schema:
            type: string
            enum: [home, away]
          example: home
        - name: result
          in: query
          schema:
            type: string
            enum: [W, L, T]
          example: W
        - name: position
          in: query
          schema:
            type: string
          example: QB
        - name: min_pass_att
          in: query
          schema:
            type: integer
          example: 20
        - name: min_rush_att
          in: query
          schema:
            type: integer
          example: 10
        - name: min_targets
          in: query
          schema:
            type: integer
          example: 8
        - name: search
          in: query
          schema:
            type: string
          example: allen
        - name: order
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Cross-player game stat results
          content:
            application/json:
              example:
                data:
                  - rank: 1
                    player_key: gsis:00-0034857
                    display_name: Josh Allen
                    team_abbr: BUF
                    opponent_abbr: JAX
                    week: 3
                    home_away: home
                    result: W
                    stat_value: 263
                    pass_yds: 263
                meta:
                  total: 1
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
                  season_year: 2024
                  season_type: REG
                  stat: pass_yds
                  order: desc
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/games/splits:
    get:
      tags:
        - Stats
      summary: Aggregate game stats into split buckets
      description: Builds grouped split summaries from the cross-player player game stat query, including top leaders in each bucket.
      operationId: listPlayerGameStatSplits
      parameters:
        - name: season_year
          in: query
          required: true
          schema:
            type: integer
          example: 2024
        - name: stat
          in: query
          required: true
          schema:
            type: string
          example: rush_yds
        - name: split_by
          in: query
          description: Grouping dimension.
          schema:
            type: string
            enum: [week, team, opponent, home_away, result, position, season_type]
            default: week
          example: team
        - name: season_type
          in: query
          schema:
            type: string
            enum: [REG, POST, ALL]
            default: ALL
          example: ALL
        - name: team
          in: query
          schema:
            type: string
          example: PHI
        - name: opponent
          in: query
          schema:
            type: string
          example: DAL
        - name: position
          in: query
          schema:
            type: string
          example: RB
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: Game stat split buckets
          content:
            application/json:
              example:
                data:
                  - split_key: PHI
                    split_by: team
                    count: 289
                    stat_total: 40698
                    stat_avg: 140.8235
                    leaders:
                      - rank: 1
                        player_key: gsis:00-0037834
                        display_name: Saquon Barkley
                        team_abbr: PHI
                        stat_value: 255
                        rush_yds: 255
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/games/leaders/{stat_family}:
    get:
      tags:
        - Stats
      summary: Query game leaders by stat family
      description: Family-specific wrapper around the player game leaderboard endpoint with a sensible default stat for each family.
      operationId: listPlayerGameStatFamilyLeaders
      parameters:
        - name: stat_family
          in: path
          required: true
          schema:
            type: string
            enum: [passing, rushing, receiving, defense, returns, kicking, punting, fumbles, misc]
          example: passing
        - name: season_year
          in: query
          required: true
          schema:
            type: integer
          example: 2024
        - name: stat
          in: query
          description: Override the default stat for the selected family.
          schema:
            type: string
          example: pass_td
        - name: season_type
          in: query
          schema:
            type: string
            enum: [REG, POST, ALL]
            default: ALL
          example: ALL
        - name: team
          in: query
          schema:
            type: string
          example: BUF
        - name: opponent
          in: query
          schema:
            type: string
          example: KC
        - name: position
          in: query
          schema:
            type: string
          example: QB
        - name: search
          in: query
          schema:
            type: string
          example: allen
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Game stat family leaderboard
          content:
            application/json:
              example:
                data:
                  - rank: 1
                    player_key: gsis:00-0034857
                    display_name: Josh Allen
                    stat_value: 4
                    pass_td: 4
                meta:
                  total: 1
                  stat_family: passing
                  stat: pass_td
                  season_year: 2024
                  season_type: ALL
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/teams:
    get:
      tags:
        - Stats
      summary: Query player production by team stint
      description: Aggregates player season stat rows by player and team abbreviation so traded-player output can be analyzed by stint.
      operationId: listPlayerTeamStints
      parameters:
        - name: search
          in: query
          schema:
            type: string
          example: sanders
        - name: team
          in: query
          schema:
            type: string
          example: SF
        - name: position
          in: query
          schema:
            type: string
          example: WR
        - name: stat
          in: query
          schema:
            type: string
          example: rec_yds
        - name: min_value
          in: query
          schema:
            type: number
          example: 500
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Player team stint rows
          content:
            application/json:
              example:
                data:
                  - player_key: namedob:deion-sanders:1967-08-09
                    display_name: Deion Sanders
                    team_abbr: DAL
                    first_season: 1995
                    last_season: 1999
                    seasons: 5
                    games: 70
                    rec_yds: 0
                    def_sacks: 0.0
                meta:
                  total: 1
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/season/{season_year}/weeks:
    get:
      tags:
        - Stats
      summary: Query weekly player leaders for a season
      description: Groups cross-player game leaderboard output into weekly or playoff-round buckets and ranks leaders inside each bucket.
      operationId: listPlayerWeeklyLeaders
      parameters:
        - name: season_year
          in: path
          required: true
          schema:
            type: integer
          example: 2024
        - name: stat
          in: query
          required: true
          schema:
            type: string
          example: rec_yds
        - name: season_type
          in: query
          schema:
            type: string
            enum: [REG, POST, ALL]
            default: ALL
          example: REG
        - name: limit_per_week
          in: query
          schema:
            type: integer
            default: 10
          example: 5
      responses:
        "200":
          description: Weekly player leaders
          content:
            application/json:
              example:
                data:
                  - bucket: REG:1
                    season_type: REG
                    week: 1
                    round: null
                    leaders:
                      - rank: 1
                        player_key: gsis:00-0033908
                        display_name: Tyreek Hill
                        stat_value: 130
                        rec_yds: 130
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/compare:
    get:
      tags:
        - Stats
      summary: Compare multiple players
      description: Returns profile, career totals, season rows, and optional game-log aggregate totals for a set of players.
      operationId: comparePlayers
      parameters:
        - name: player_keys
          in: query
          required: true
          description: Comma-separated player keys. Minimum two.
          schema:
            type: string
          example: gsis:00-0034857,gsis:00-0033873
        - name: season_years
          in: query
          description: Optional comma-separated season filter.
          schema:
            type: string
          example: 2023,2024
        - name: include_games
          in: query
          description: Include aggregated game-log totals for each player.
          schema:
            type: boolean
          example: true
      responses:
        "200":
          description: Player comparison payload
          content:
            application/json:
              example:
                data:
                  players:
                    - profile:
                        player_key: gsis:00-0034857
                        display_name: Josh Allen
                        position: QB
                        latest_team_abbr: BUF
                      career:
                        pass_yds: 26434
                        pass_td: 195
                      seasons:
                        - season_year: 2024
                          season_type: REG
                          pass_yds: 3731
                          pass_td: 28
                      game_totals:
                        games: 111
                        pass_yds: 26434
                    - profile:
                        player_key: gsis:00-0033873
                        display_name: Lamar Jackson
                        position: QB
                        latest_team_abbr: BAL
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/stats/players/search:
    get:
      tags:
        - Stats
      summary: Search players with stat coverage metadata
      description: Player search endpoint with attached career coverage and season-row availability metadata.
      operationId: searchPlayersWithStats
      parameters:
        - name: search
          in: query
          schema:
            type: string
          example: barkley
        - name: team
          in: query
          schema:
            type: string
          example: PHI
        - name: position
          in: query
          schema:
            type: string
          example: RB
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Player search results with stat metadata
          content:
            application/json:
              example:
                data:
                  - player_key: gsis:00-0037834
                    display_name: Saquon Barkley
                    position: RB
                    latest_team_abbr: PHI
                    stats:
                      seasons_played: 7
                      seasons_with_stats: 7
                      tracked_stat_games: 98
                      stat_coverage_start_season: 2018
                      stat_coverage_end_season: 2024
                    coverage:
                      first_stat_season: 2018
                      last_stat_season: 2024
                      season_rows: 7
                meta:
                  total: 1
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/games:
    get:
      tags:
        - Games
      summary: Query games index
      description: Browse regular-season and playoff games with simple season, week, team, and date filters. Start here when you need to discover a game id before calling a detail endpoint.
      operationId: listGames
      parameters:
        - name: season
          in: query
          description: NFL season year to filter on. Use the season label, not the calendar year of the game date.
          schema:
            type: integer
          example: 2025
        - name: week
          in: query
          description: Regular-season week number. Most useful together with season.
          schema:
            type: integer
          example: 1
        - name: team
          in: query
          description: Team abbreviation or numeric team id. Returns games where that team was either home or away.
          schema:
            type: string
          example: PIT
        - name: date
          in: query
          description: Exact game date in YYYY-MM-DD format.
          schema:
            type: string
            format: date
          example: 2025-09-07
        - name: order
          in: query
          description: Sort order for the returned games.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: include_playoffs
          in: query
          description: Include playoff games in the result set when true.
          schema:
            type: boolean
            default: true
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Games list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GamesListResponse"
              example:
                data:
                  - id: 12001
                    isPlayoff: false
                    seasonYear: 2025
                    week: 1
                    round: null
                    gameDate: 2025-09-07
                    kickoffAt: 2025-09-07T13:00:00-04:00
                    awayAbbr: PIT
                    awayName: Pittsburgh Steelers
                    homeAbbr: BAL
                    homeName: Baltimore Ravens
                    awayScore: 20
                    homeScore: 17
                    broadcastNetwork: CBS
                    stadium: M&T Bank Stadium
                meta:
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
                  order: desc
                  include_playoffs: true
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/games/{id}:
    get:
      tags:
        - Games
      summary: Get game detail
      operationId: getGame
      parameters:
        - $ref: "#/components/parameters/gameId"
      responses:
        "200":
          description: Game detail
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/GameDetail"
              example:
                data:
                  id: 12001
                  season_year: 2025
                  week: 1
                  round: null
                  game_date: 2025-09-07
                  kickoff_at: 2025-09-07T13:00:00-04:00
                  title: Pittsburgh at Baltimore
                  away_team:
                    id: 24
                    abbr: PIT
                    city: Pittsburgh
                    nickname: Steelers
                    full_name: Pittsburgh Steelers
                  home_team:
                    id: 3
                    abbr: BAL
                    city: Baltimore
                    nickname: Ravens
                    full_name: Baltimore Ravens
                  away_coach:
                    name: Mike Tomlin
                    photo_path: /media/coach-photos/custom/mike-tomlin.jpg?v=1
                  home_coach:
                    name: John Harbaugh
                    photo_path: /media/coach-photos/john_harbaugh.jpg
                  away_score: 20
                  home_score: 17
                  stadium: M&T Bank Stadium
                  broadcast_network: CBS
                  announcers: Ian Eagle, Charles Davis
                  summary: Steelers edge Ravens in a late defensive battle.
                  is_playoff: null
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/games/{id}/{field}:
    get:
      tags:
        - Games
      summary: Get one game detail field
      description: Returns a single top-level field from the regular game detail payload. Supported fields include id, season_year, week, round, game_date, kickoff_at, title, away_team, home_team, away_coach, home_coach, away_score, home_score, stadium, broadcast_network, announcers, summary, and is_playoff.
      operationId: getGameField
      parameters:
        - $ref: "#/components/parameters/gameId"
        - name: field
          in: path
          required: true
          description: Top-level field name from the game detail payload.
          schema:
            type: string
          example: stadium
      responses:
        "200":
          description: Game detail field value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: stadium
                  value: M&T Bank Stadium
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/games/{id}/extras:
    get:
      tags:
        - Games
      summary: Get regular game extras
      operationId: getGameExtras
      parameters:
        - $ref: "#/components/parameters/gameId"
      responses:
        "200":
          description: Advanced game extras
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: "#/components/schemas/GameExtras"
                  meta:
                    type: object
                    properties:
                      canonical_game_id:
                        type: integer
              example:
                data:
                  teamStats:
                    away:
                      abbr: PIT
                      stats:
                        - label: Total Yards
                          away: "327"
                          home: "301"
                    home:
                      abbr: BAL
                      stats:
                        - label: Total Yards
                          away: "327"
                          home: "301"
                  expectedPoints:
                    PIT:
                      total: "3.1"
                      offense: {}
                      defense: {}
                      specialTeams: {}
                  gameInfo:
                    - info: Weather
                      stat: 68F, clear
                  officials:
                    - role: Referee
                      name: Clete Blakeman
                  homeStarters: []
                  awayStarters: []
                  stadiumMeta:
                    name: M&T Bank Stadium
                    capacity: 71008
                    surface: Grass
                    location: Baltimore, MD
                    inauguralDate: 1998-09-06
                    logoUrl: https://nflmeta.org/assets/stadiums/mt_bank.png
                meta:
                  canonical_game_id: 12001
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/playoff-games/{id}:
    get:
      tags:
        - Playoffs
      summary: Get playoff game detail
      operationId: getPlayoffGame
      parameters:
        - name: id
          in: path
          required: true
          description: Canonical playoff game id.
          schema:
            type: integer
          example: 1894
      responses:
        "200":
          description: Playoff game detail
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/GameDetail"
              example:
                data:
                  id: 9901
                  season_year: 2025
                  week: null
                  round: conference
                  game_date: 2026-01-25
                  kickoff_at: 2026-01-25T18:30:00-05:00
                  title: Buffalo at Kansas City
                  away_team:
                    id: 2
                    abbr: BUF
                    city: Buffalo
                    nickname: Bills
                    full_name: Buffalo Bills
                  home_team:
                    id: 14
                    abbr: KC
                    city: Kansas City
                    nickname: Chiefs
                    full_name: Kansas City Chiefs
                  away_coach:
                    name: Sean McDermott
                    photo_path: /media/coach-photos/sean_mcdermott.jpg
                  home_coach:
                    name: Andy Reid
                    photo_path: /media/coach-photos/andy_reid.jpg
                  away_score: 24
                  home_score: 27
                  stadium: GEHA Field at Arrowhead Stadium
                  broadcast_network: CBS
                  announcers: null
                  summary: Chiefs advance to the Super Bowl.
                  is_playoff: true
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/playoff-games/{id}/{field}:
    get:
      tags:
        - Playoffs
      summary: Get one playoff game detail field
      description: Returns a single top-level field from the playoff game detail payload. Supported fields include id, season_year, week, round, game_date, kickoff_at, title, away_team, home_team, away_coach, home_coach, away_score, home_score, stadium, broadcast_network, announcers, summary, and is_playoff.
      operationId: getPlayoffGameField
      parameters:
        - name: id
          in: path
          required: true
          description: Canonical playoff game id.
          schema:
            type: integer
          example: 1894
        - name: field
          in: path
          required: true
          description: Top-level field name from the playoff game detail payload.
          schema:
            type: string
          example: round
      responses:
        "200":
          description: Playoff game detail field value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: round
                  value: conference
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/playoff-games/{id}/extras:
    get:
      tags:
        - Playoffs
      summary: Get playoff game extras
      operationId: getPlayoffGameExtras
      parameters:
        - name: id
          in: path
          required: true
          description: Canonical playoff game id.
          schema:
            type: integer
          example: 1894
      responses:
        "200":
          description: Playoff game extras
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/GameExtras"
              example:
                data:
                  teamStats:
                    away:
                      abbr: BUF
                      stats:
                        - label: Total Yards
                          away: "345"
                          home: "371"
                    home:
                      abbr: KC
                      stats:
                        - label: Total Yards
                          away: "345"
                          home: "371"
                  expectedPoints: null
                  gameInfo: []
                  officials: []
                  homeStarters:
                    - pos: QB
                      player: Patrick Mahomes
                  awayStarters:
                    - pos: QB
                      player: Josh Allen
                  stadiumMeta:
                    name: GEHA Field at Arrowhead Stadium
                    capacity: 76416
                    surface: Grass
                    location: Kansas City, MO
                    inauguralDate: 1972-08-12
                    logoUrl: https://nflmeta.org/assets/stadiums/arrowhead.png
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/standings:
    get:
      tags:
        - Standings
      summary: Get standings
      operationId: getStandings
      parameters:
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Standings payload
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/StandingsPayload"
              example:
                data:
                  seasonYear: 2025
                  seasonYears:
                    - 2025
                    - 2024
                    - 2023
                  grouped:
                    AFC:
                      North:
                        - teamId: 24
                          teamAbbr: PIT
                          teamName: Pittsburgh Steelers
                          conference: AFC
                          division: North
                          wins: 10
                          losses: 7
                          ties: 0
                          gamesPlayed: 17
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/playoffs/picture:
    get:
      tags:
        - Playoffs
      summary: Get playoff picture
      operationId: getPlayoffPicture
      parameters:
        - name: season
          in: query
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Playoff picture by round and conference
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/PlayoffPicturePayload"
              example:
                data:
                  seasonYear: 2025
                  seasonYears:
                    - 2025
                    - 2024
                  rounds:
                    wild_card:
                      afc: []
                      nfc: []
                      other: []
                    divisional:
                      afc: []
                      nfc: []
                      other: []
                    conference:
                      afc:
                        - id: 9901
                          seasonYear: 2025
                          round: conference
                          conference: AFC
                          gameDate: 2026-01-25
                          awayName: Buffalo Bills
                          homeName: Kansas City Chiefs
                          awayScore: 24
                          homeScore: 27
                      nfc: []
                      other: []
                    super_bowl:
                      afc: []
                      nfc: []
                      other:
                        - id: 9902
                          seasonYear: 2025
                          round: super_bowl
                          conference: ""
                          gameDate: 2026-02-08
                          awayName: Kansas City Chiefs
                          homeName: Philadelphia Eagles
                          awayScore: null
                          homeScore: null
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/super-bowls:
    get:
      tags:
        - Super Bowls
      summary: List super bowl records
      operationId: listSuperBowls
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Super bowl list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuperBowlsListResponse"
              example:
                data:
                  - id: 9902
                    seasonYear: 2025
                    gameDate: 2026-02-08
                    title: Super Bowl LX
                    homeName: Philadelphia Eagles
                    awayName: Kansas City Chiefs
                    homeScore: null
                    awayScore: null
                    winnerName: null
                    isPlaceholder: false
                meta:
                  total: 1
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/super-bowls/{season_year}:
    get:
      tags:
        - Super Bowls
      summary: Get super bowl for season
      operationId: getSuperBowlBySeason
      parameters:
        - name: season_year
          in: path
          required: true
          schema:
            type: integer
          example: 2025
      responses:
        "200":
          description: Super bowl record
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/SuperBowlItem"
              example:
                data:
                  id: 9902
                  seasonYear: 2025
                  gameDate: 2026-02-08
                  title: Super Bowl LX
                  homeName: Philadelphia Eagles
                  awayName: Kansas City Chiefs
                  homeScore: null
                  awayScore: null
                  winnerName: null
                  isPlaceholder: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/super-bowls/teams/{abbr}:
    get:
      tags:
        - Super Bowls
      summary: Get super bowl record for team
      operationId: getSuperBowlTeamRecord
      parameters:
        - $ref: "#/components/parameters/teamAbbr"
      responses:
        "200":
          description: Team super bowl record
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/SuperBowlTeamRecord"
              example:
                data:
                  teamAbbr: PIT
                  teamName: Pittsburgh Steelers
                  wins: 6
                  appearances: 8
                  games:
                    - id: 8801
                      seasonYear: 2008
                      gameDate: 2009-02-01
                      title: Super Bowl XLIII
                      homeName: Pittsburgh Steelers
                      awayName: Arizona Cardinals
                      homeScore: 27
                      awayScore: 23
                      winnerName: Pittsburgh Steelers
                      isPlaceholder: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/history/stadiums:
    get:
      tags:
        - History
      summary: List stadium history timeline
      operationId: listStadiumHistory
      parameters:
        - name: team
          in: query
          schema:
            type: string
          example: PIT
        - name: year
          in: query
          schema:
            type: integer
          example: 2005
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Stadium history
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StadiumHistoryResponse"
              example:
                data:
                  - id: 101
                    teamId: 24
                    teamAbbr: PIT
                    teamName: Pittsburgh Steelers
                    stadiumName: Acrisure Stadium
                    startYear: 2001
                    endYear: null
                    inauguralDate: 2001-08-18
                    logoPath: stadiums/acrisure.png
                meta:
                  total: 1
                  limit: 250
                  offset: 0
                  returned: 1
                  has_more: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/history/team-logos:
    get:
      tags:
        - History
      summary: List team logo history timeline
      operationId: listTeamLogoHistory
      parameters:
        - name: team
          in: query
          schema:
            type: string
          example: PIT
        - name: source
          in: query
          schema:
            type: string
          example: sportslogos
        - name: year
          in: query
          schema:
            type: integer
          example: 1995
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Team logo history
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamLogoHistoryResponse"
              example:
                data:
                  - id: 88
                    teamId: 24
                    teamAbbr: PIT
                    teamName: Pittsburgh Steelers
                    startYear: 1969
                    endYear: null
                    logoName: Steelmark Helmet
                    logoUrl: https://example.com/pit-logo.png
                    source: sportslogos
                meta:
                  total: 1
                  limit: 250
                  offset: 0
                  returned: 1
                  has_more: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/hall-of-fame:
    get:
      tags:
        - Hall of Fame
      summary: List Hall of Fame nominees
      description: Returns Hall of Fame nominee rows across election years with optional year, role, ballot, and inductee filters.
      operationId: listHallOfFameNominees
      parameters:
        - name: search
          in: query
          schema:
            type: string
          example: nunn
        - name: role
          in: query
          schema:
            type: string
            enum:
              - player
              - coach
              - contributor
          example: contributor
        - name: ballot_type
          in: query
          schema:
            type: string
            enum:
              - inductee
              - final
              - senior
              - semi
          example: final
        - name: inductee
          in: query
          schema:
            type: boolean
          example: true
        - name: year_from
          in: query
          schema:
            type: integer
          example: 2000
        - name: year_to
          in: query
          schema:
            type: integer
          example: 2026
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Hall of Fame nominee list
          content:
            application/json:
              example:
                data:
                  - id: 1
                    election_year: 2021
                    ballot_type: inductee
                    nominee_name: Bill Nunn
                    role_label: Contributor
                    recipient_role: contributor
                    is_inductee: true
                    induction_year: 2021
                    contributor_key: bill-nunn
                meta:
                  total: 1
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/hall-of-fame/{election_year}:
    get:
      tags:
        - Hall of Fame
      summary: Get one Hall of Fame election year
      description: Returns the grouped nominee ballot for one election year.
      operationId: getHallOfFameElectionYear
      parameters:
        - name: election_year
          in: path
          required: true
          schema:
            type: integer
          example: 2021
      responses:
        "200":
          description: Hall of Fame election year
          content:
            application/json:
              example:
                data:
                  election_year: 2021
                  total_nominees: 15
                  inductee_count: 8
                  groups:
                    - ballot_type: inductee
                      recipient_role: contributor
                      label: Inductee • Contributor
                      nominees:
                        - nominee_name: Bill Nunn
                          contributor_key: bill-nunn
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/hall-of-fame/{election_year}/{field}:
    get:
      tags:
        - Hall of Fame
      summary: Get one Hall of Fame election-year field
      description: Returns a single field from the Hall of Fame election-year payload. Supported fields include election_year, total_nominees, inductee_count, and groups.
      operationId: getHallOfFameElectionYearField
      parameters:
        - name: election_year
          in: path
          required: true
          schema:
            type: integer
          example: 2021
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: inductee_count
      responses:
        "200":
          description: Hall of Fame election-year field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: inductee_count
                  value: 8
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/contributors:
    get:
      tags:
        - Contributors
      summary: List contributors
      description: Returns contributor-only Hall of Fame people not currently represented as players, coaches, or executives.
      operationId: listContributors
      parameters:
        - name: search
          in: query
          schema:
            type: string
          example: nunn
        - name: inductee
          in: query
          schema:
            type: boolean
          example: true
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Contributor records
          content:
            application/json:
              example:
                data:
                  - contributor_key: bill-nunn
                    display_name: Bill Nunn
                    role_label: Contributor
                    photo_url: https://upload.wikimedia.org/example.jpg
                    is_inductee: true
                    induction_year: 2021
                meta:
                  total: 1
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/contributors/{contributor_key}:
    get:
      tags:
        - Contributors
      summary: Get curated contributor profile
      description: Returns a structured contributor resource with identity, bio, and Hall of Fame history slices.
      operationId: getContributorProfile
      parameters:
        - name: contributor_key
          in: path
          required: true
          schema:
            type: string
          example: bill-nunn
      responses:
        "200":
          description: Contributor profile
          content:
            application/json:
              example:
                data:
                  identity:
                    contributor_key: bill-nunn
                    display_name: Bill Nunn
                    role_label: Contributor
                    is_inductee: true
                  bio:
                    wikipedia_description: American football scout
                  history:
                    induction_year: 2021
                    nomination_count: 2
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/contributors/{contributor_key}/identity:
    get:
      tags:
        - Contributors
      summary: Get contributor identity slice
      operationId: getContributorIdentity
      parameters:
        - name: contributor_key
          in: path
          required: true
          schema:
            type: string
          example: bill-nunn
      responses:
        "200":
          description: Contributor identity
          content:
            application/json:
              example:
                data:
                  contributor_key: bill-nunn
                  display_name: Bill Nunn
                  role_label: Contributor
                  is_inductee: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/contributors/{contributor_key}/identity/{field}:
    get:
      tags:
        - Contributors
      summary: Get one contributor identity field
      operationId: getContributorIdentityField
      parameters:
        - name: contributor_key
          in: path
          required: true
          schema:
            type: string
          example: bill-nunn
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: display_name
      responses:
        "200":
          description: Contributor identity field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: display_name
                  value: Bill Nunn
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/contributors/{contributor_key}/bio:
    get:
      tags:
        - Contributors
      summary: Get contributor bio slice
      operationId: getContributorBio
      parameters:
        - name: contributor_key
          in: path
          required: true
          schema:
            type: string
          example: bill-nunn
      responses:
        "200":
          description: Contributor bio
          content:
            application/json:
              example:
                data:
                  wikipedia_description: American football scout
                  wikipedia_url: https://en.wikipedia.org/wiki/Bill_Nunn_(American_football)
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/contributors/{contributor_key}/bio/{field}:
    get:
      tags:
        - Contributors
      summary: Get one contributor bio field
      operationId: getContributorBioField
      parameters:
        - name: contributor_key
          in: path
          required: true
          schema:
            type: string
          example: bill-nunn
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: wikipedia_summary
      responses:
        "200":
          description: Contributor bio field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: wikipedia_description
                  value: American football scout
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/contributors/{contributor_key}/history:
    get:
      tags:
        - Contributors
      summary: Get contributor history slice
      operationId: getContributorHistory
      parameters:
        - name: contributor_key
          in: path
          required: true
          schema:
            type: string
          example: bill-nunn
      responses:
        "200":
          description: Contributor history
          content:
            application/json:
              example:
                data:
                  first_hof_election_year: 2020
                  latest_hof_election_year: 2021
                  induction_year: 2021
                  nomination_count: 2
                  raw_row: []
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/contributors/{contributor_key}/history/{field}:
    get:
      tags:
        - Contributors
      summary: Get one contributor history field
      operationId: getContributorHistoryField
      parameters:
        - name: contributor_key
          in: path
          required: true
          schema:
            type: string
          example: bill-nunn
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: induction_year
      responses:
        "200":
          description: Contributor history field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: induction_year
                  value: 2021
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/executives:
    get:
      tags:
        - Executives
      summary: List executives
      description: Returns executive reference rows with optional search, team-text, and Hall of Fame filters.
      operationId: listExecutives
      parameters:
        - name: search
          in: query
          schema:
            type: string
          example: kraft
        - name: team
          in: query
          schema:
            type: string
          example: patriots
        - name: hall_of_fame
          in: query
          schema:
            type: boolean
          example: true
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Executive records
          content:
            application/json:
              example:
                data:
                  - executive_key: robert-kraft
                    display_name: Robert Kraft
                    teams_text: Patriots
                    positions_text: Owner
                    hall_of_fame: false
                meta:
                  total: 1
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/executives/{executive_key}:
    get:
      tags:
        - Executives
      summary: Get curated executive profile
      description: Returns a structured executive resource with identity, bio, career, and history slices.
      operationId: getExecutiveProfile
      parameters:
        - name: executive_key
          in: path
          required: true
          schema:
            type: string
          example: robert-kraft
      responses:
        "200":
          description: Executive profile
          content:
            application/json:
              example:
                data:
                  identity:
                    executive_key: robert-kraft
                    display_name: Robert Kraft
                    hall_of_fame: false
                  bio:
                    teams_text: Patriots
                    positions_text: Owner
                  career:
                    first_year: 1994
                    last_year: 2026
                    years_total: 33
                  history:
                    hall_of_fame: false
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/executives/{executive_key}/identity:
    get:
      tags:
        - Executives
      summary: Get executive identity slice
      operationId: getExecutiveIdentity
      parameters:
        - name: executive_key
          in: path
          required: true
          schema:
            type: string
          example: robert-kraft
      responses:
        "200":
          description: Executive identity
          content:
            application/json:
              example:
                data:
                  executive_key: robert-kraft
                  display_name: Robert Kraft
                  hall_of_fame: false
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/executives/{executive_key}/identity/{field}:
    get:
      tags:
        - Executives
      summary: Get one executive identity field
      operationId: getExecutiveIdentityField
      parameters:
        - name: executive_key
          in: path
          required: true
          schema:
            type: string
          example: robert-kraft
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: display_name
      responses:
        "200":
          description: Executive identity field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: display_name
                  value: Robert Kraft
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/executives/{executive_key}/bio:
    get:
      tags:
        - Executives
      summary: Get executive bio slice
      operationId: getExecutiveBio
      parameters:
        - name: executive_key
          in: path
          required: true
          schema:
            type: string
          example: robert-kraft
      responses:
        "200":
          description: Executive bio
          content:
            application/json:
              example:
                data:
                  teams_text: Patriots
                  positions_text: Owner
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/executives/{executive_key}/bio/{field}:
    get:
      tags:
        - Executives
      summary: Get one executive bio field
      operationId: getExecutiveBioField
      parameters:
        - name: executive_key
          in: path
          required: true
          schema:
            type: string
          example: robert-kraft
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: teams_text
      responses:
        "200":
          description: Executive bio field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: teams_text
                  value: Patriots
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/executives/{executive_key}/career:
    get:
      tags:
        - Executives
      summary: Get executive career slice
      operationId: getExecutiveCareer
      parameters:
        - name: executive_key
          in: path
          required: true
          schema:
            type: string
          example: robert-kraft
      responses:
        "200":
          description: Executive career
          content:
            application/json:
              example:
                data:
                  first_year: 1994
                  last_year: 2026
                  years_total: 33
                  teams_text: Patriots
                  positions_text: Owner
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/executives/{executive_key}/career/{field}:
    get:
      tags:
        - Executives
      summary: Get one executive career field
      operationId: getExecutiveCareerField
      parameters:
        - name: executive_key
          in: path
          required: true
          schema:
            type: string
          example: robert-kraft
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: years_total
      responses:
        "200":
          description: Executive career field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: years_total
                  value: 33
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/executives/{executive_key}/history:
    get:
      tags:
        - Executives
      summary: Get executive history slice
      operationId: getExecutiveHistory
      parameters:
        - name: executive_key
          in: path
          required: true
          schema:
            type: string
          example: robert-kraft
      responses:
        "200":
          description: Executive history
          content:
            application/json:
              example:
                data:
                  hall_of_fame: false
                  raw_row:
                    Name: Robert Kraft
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/executives/{executive_key}/history/{field}:
    get:
      tags:
        - Executives
      summary: Get one executive history field
      operationId: getExecutiveHistoryField
      parameters:
        - name: executive_key
          in: path
          required: true
          schema:
            type: string
          example: robert-kraft
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: hall_of_fame
      responses:
        "200":
          description: Executive history field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: hall_of_fame
                  value: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/staff:
    get:
      tags:
        - Staff
      summary: List current staff
      description: Returns current staff rows from the active team staff dataset with search, team, role-group, title, and linked-coach filters.
      operationId: listStaff
      parameters:
        - name: search
          in: query
          schema:
            type: string
          example: cignetti
        - name: team
          in: query
          schema:
            type: string
          example: steelers
        - name: group
          in: query
          schema:
            type: string
          example: offense
        - name: title
          in: query
          schema:
            type: string
          example: quarterbacks
        - name: linked_to_coach
          in: query
          schema:
            type: boolean
          example: true
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Current staff records
          content:
            application/json:
              example:
                data:
                  - staff_key: frank-cignetti-jr
                    coach_key: frank-cignetti-jr
                    display_name: Frank Cignetti Jr.
                    source_name: Frank Cignetti Jr.
                    team_abbr: PIT
                    team_name: Pittsburgh Steelers
                    season_year: 2026
                    role_title: Senior Offensive Assistant
                    role_group: Offense
                    photo_url: https://static.clubs.nfl.com/example.jpg
                    with_team_since_year: 2026
                    experience_years: 12
                meta:
                  season_year: 2026
                  total: 1
                  limit: 50
                  offset: 0
                  returned: 1
                  has_more: false
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/staff/{staff_key}:
    get:
      tags:
        - Staff
      summary: Get curated staff profile
      description: Returns a structured current staff resource with identity, bio, career, and source-history slices.
      operationId: getStaffProfile
      parameters:
        - name: staff_key
          in: path
          required: true
          schema:
            type: string
          example: frank-cignetti-jr
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
      responses:
        "200":
          description: Staff profile
          content:
            application/json:
              example:
                data:
                  identity:
                    staff_key: frank-cignetti-jr
                    coach_key: frank-cignetti-jr
                    display_name: Frank Cignetti Jr.
                    team_abbr: PIT
                    season_year: 2026
                  bio:
                    biography: Frank Cignetti Jr. enters the 2026 season as Pittsburgh's senior offensive assistant after prior coordinator and quarterbacks-coach stops across the NFL and college football.
                    college_name: IUP
                  career:
                    role_title: Senior Offensive Assistant
                    role_group: Offense
                    with_team_since_year: 2026
                    experience_years: 12
                  history:
                    source_site: steelers.com
                    source_path: /team/coaches-roster/frank-cignetti-jr
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/staff/{staff_key}/identity:
    get:
      tags:
        - Staff
      summary: Get staff identity slice
      operationId: getStaffIdentity
      parameters:
        - name: staff_key
          in: path
          required: true
          schema:
            type: string
          example: frank-cignetti-jr
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
      responses:
        "200":
          description: Staff identity
          content:
            application/json:
              example:
                data:
                  staff_key: frank-cignetti-jr
                  coach_key: frank-cignetti-jr
                  display_name: Frank Cignetti Jr.
                  team_abbr: PIT
                  team_name: Pittsburgh Steelers
                  season_year: 2026
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/staff/{staff_key}/identity/{field}:
    get:
      tags:
        - Staff
      summary: Get one staff identity field
      operationId: getStaffIdentityField
      parameters:
        - name: staff_key
          in: path
          required: true
          schema:
            type: string
          example: frank-cignetti-jr
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: team_abbr
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
      responses:
        "200":
          description: Staff identity field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: team_abbr
                  value: PIT
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/staff/{staff_key}/bio:
    get:
      tags:
        - Staff
      summary: Get staff bio slice
      operationId: getStaffBio
      parameters:
        - name: staff_key
          in: path
          required: true
          schema:
            type: string
          example: frank-cignetti-jr
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
      responses:
        "200":
          description: Staff bio
          content:
            application/json:
              example:
                data:
                  biography: Frank Cignetti Jr. enters the 2026 season as Pittsburgh's senior offensive assistant after prior coordinator and quarterbacks-coach stops across the NFL and college football.
                  college_name: IUP
                  birth_place: Pittsburgh, Pennsylvania
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/staff/{staff_key}/bio/{field}:
    get:
      tags:
        - Staff
      summary: Get one staff bio field
      operationId: getStaffBioField
      parameters:
        - name: staff_key
          in: path
          required: true
          schema:
            type: string
          example: frank-cignetti-jr
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: biography
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
      responses:
        "200":
          description: Staff bio field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: college_name
                  value: IUP
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/staff/{staff_key}/career:
    get:
      tags:
        - Staff
      summary: Get staff career slice
      operationId: getStaffCareer
      parameters:
        - name: staff_key
          in: path
          required: true
          schema:
            type: string
          example: frank-cignetti-jr
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
      responses:
        "200":
          description: Staff career
          content:
            application/json:
              example:
                data:
                  role_title: Senior Offensive Assistant
                  role_group: Offense
                  season_year: 2026
                  with_team_since_year: 2026
                  experience_years: 12
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/staff/{staff_key}/career/{field}:
    get:
      tags:
        - Staff
      summary: Get one staff career field
      operationId: getStaffCareerField
      parameters:
        - name: staff_key
          in: path
          required: true
          schema:
            type: string
          example: frank-cignetti-jr
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: role_title
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
      responses:
        "200":
          description: Staff career field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: role_title
                  value: Senior Offensive Assistant
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/staff/{staff_key}/history:
    get:
      tags:
        - Staff
      summary: Get staff source-history slice
      operationId: getStaffHistory
      parameters:
        - name: staff_key
          in: path
          required: true
          schema:
            type: string
          example: frank-cignetti-jr
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
      responses:
        "200":
          description: Staff source-history
          content:
            application/json:
              example:
                data:
                  record_key: PIT-2026-frank-cignetti-jr
                  source_site: steelers.com
                  source_path: /team/coaches-roster/frank-cignetti-jr
                  profile_url: https://www.steelers.com/team/coaches-roster/frank-cignetti-jr/
                  raw_row:
                    title: Senior Offensive Assistant
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/staff/{staff_key}/history/{field}:
    get:
      tags:
        - Staff
      summary: Get one staff history field
      operationId: getStaffHistoryField
      parameters:
        - name: staff_key
          in: path
          required: true
          schema:
            type: string
          example: frank-cignetti-jr
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: source_site
        - name: season_year
          in: query
          schema:
            type: integer
          example: 2026
      responses:
        "200":
          description: Staff history field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: source_site
                  value: steelers.com
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/coaches:
    get:
      tags:
        - Metadata
      summary: List coaches
      operationId: listCoaches
      responses:
        "200":
          description: Coach records
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    properties:
                      coaches:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            photo_path:
                              type:
                                - string
                                - "null"
                            team:
                              type:
                                - string
                                - "null"
                            season_year:
                              type: integer
              example:
                data:
                  coaches:
                    - name: Mike Tomlin
                      photo_path: /coach_photos/custom/mike-tomlin.jpg?v=1
                      team: Pittsburgh Steelers
                      season_year: 2025
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401": &a5
          $ref: "#/components/responses/Unauthorized"
  /api/v1/reference/coaches/{coach_key}:
    get:
      tags:
        - Reference
      summary: Get raw coach record
      description: Returns the table-shaped raw coach row for one coach key, including source columns and parsed raw_row data when present.
      operationId: getReferenceCoach
      parameters:
        - $ref: "#/components/parameters/coachKey"
      responses:
        "200":
          description: Raw coach record
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/ReferenceCoachRecord"
              example:
                data:
                  coach_key: mike-tomlin
                  display_name: Mike Tomlin
                  first_year: 2007
                  last_year: 2025
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/reference/coaches/{coach_key}/{field}:
    get:
      tags:
        - Reference
      summary: Get one raw coach field
      description: Returns a single field from the raw coach record.
      operationId: getReferenceCoachField
      parameters:
        - $ref: "#/components/parameters/coachKey"
        - name: field
          in: path
          required: true
          description: Field name from the raw coach record.
          schema:
            type: string
          example: display_name
      responses:
        "200":
          description: Raw coach field value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: display_name
                  value: Mike Tomlin
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/coaches/{coach_key}:
    get:
      tags:
        - Coaches
      summary: Get curated coach profile
      description: Returns a structured coach resource with identity, bio, career, and history slices.
      operationId: getCoachProfile
      parameters:
        - $ref: "#/components/parameters/coachKey"
      responses:
        "200":
          description: Coach profile
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/CoachProfile"
              example:
                data:
                  identity:
                    coach_key: mike-tomlin
                    display_name: Mike Tomlin
                    source_name: Mike Tomlin
                    photo_path: /media/coach-photos/custom/mike-tomlin.jpg?v=1
                    hall_of_fame: false
                    rank: 12
                  bio:
                    birth_date: 1972-03-15
                    birth_place: Hampton, Virginia
                    college_name: William & Mary
                    playing_position: WR
                  career:
                    first_year: 2007
                    last_year: 2025
                    regular_wins: 183
                    playoff_wins: 8
                    super_bowls: 1
                  history:
                    history: []
                    awards: []
                    team_records: []
                    stadium_summaries: []
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/coaches/{coach_key}/identity:
    get:
      tags:
        - Coaches
      summary: Get coach identity slice
      description: Returns name, photo, Hall of Fame, and rank fields for one coach.
      operationId: getCoachIdentity
      parameters:
        - $ref: "#/components/parameters/coachKey"
      responses:
        "200":
          description: Coach identity
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/CoachIdentity"
              example:
                data:
                  coach_key: mike-tomlin
                  display_name: Mike Tomlin
                  source_name: Mike Tomlin
                  photo_path: /media/coach-photos/custom/mike-tomlin.jpg?v=1
                  hall_of_fame: false
                  rank: 12
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/coaches/{coach_key}/identity/{field}:
    get:
      tags:
        - Coaches
      summary: Get one coach identity field
      description: Returns a single field from the coach identity slice. Supported fields include coach_key, display_name, source_name, photo_path, hall_of_fame, and rank.
      operationId: getCoachIdentityField
      parameters:
        - $ref: "#/components/parameters/coachKey"
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: display_name
      responses:
        "200":
          description: Coach identity field value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: display_name
                  value: Mike Tomlin
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/coaches/{coach_key}/bio:
    get:
      tags:
        - Coaches
      summary: Get coach bio slice
      description: Returns birth, college, playing-background, and narrative bio fields for one coach.
      operationId: getCoachBio
      parameters:
        - $ref: "#/components/parameters/coachKey"
      responses:
        "200":
          description: Coach bio
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/CoachBio"
              example:
                data:
                  birth_date: 1972-03-15
                  birth_place: Hampton, Virginia
                  college_name: William & Mary
                  playing_position: WR
                  played_in_nfl: false
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/coaches/{coach_key}/bio/{field}:
    get:
      tags:
        - Coaches
      summary: Get one coach bio field
      description: Returns a single field from the coach bio slice. Supported fields include birth_date, birth_place, death_date, death_place, college_name, playing_position, bio_summary, did_you_know, playing_career_summary, playing_college_years, pro_football_hall_of_fame_year, playing_nfl_years, playing_nfl_teams, and played_in_nfl.
      operationId: getCoachBioField
      parameters:
        - $ref: "#/components/parameters/coachKey"
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: birth_place
      responses:
        "200":
          description: Coach bio field value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: birth_place
                  value: Hampton, Virginia
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/coaches/{coach_key}/career:
    get:
      tags:
        - Coaches
      summary: Get coach career slice
      description: Returns aggregate coaching results and title metrics for one coach.
      operationId: getCoachCareer
      parameters:
        - $ref: "#/components/parameters/coachKey"
      responses:
        "200":
          description: Coach career
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/CoachCareer"
              example:
                data:
                  first_year: 2007
                  last_year: 2025
                  years_total: 19
                  regular_games: 306
                  regular_wins: 183
                  playoff_games: 18
                  playoff_wins: 8
                  championships: 1
                  super_bowls: 1
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/coaches/{coach_key}/career/{field}:
    get:
      tags:
        - Coaches
      summary: Get one coach career field
      description: Returns a single field from the coach career slice. Supported fields include first_year, last_year, years_total, regular_games, regular_wins, regular_losses, regular_ties, regular_win_pct, playoff_years, playoff_games, playoff_wins, playoff_losses, playoff_win_pct, championships, super_bowls, conference_titles, average_rank, and best_rank.
      operationId: getCoachCareerField
      parameters:
        - $ref: "#/components/parameters/coachKey"
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: regular_wins
      responses:
        "200":
          description: Coach career field value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: regular_wins
                  value: 183
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/coaches/{coach_key}/history:
    get:
      tags:
        - Coaches
      summary: Get coach history slice
      description: Returns team history, award summaries, team-record stints, and stadium summaries for one coach.
      operationId: getCoachHistory
      parameters:
        - $ref: "#/components/parameters/coachKey"
      responses:
        "200":
          description: Coach history
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/CoachHistory"
              example:
                data:
                  history:
                    - season_year: 2025
                      team_abbr: PIT
                      team_name: Pittsburgh Steelers
                  awards:
                    - award_name: AP Coach of the Year
                      award_count: 1
                      first_year: 2008
                      last_year: 2008
                  team_records:
                    - team_abbr: PIT
                      first_year: 2007
                      last_year: 2025
                      wins: 183
                      losses: 107
                  stadium_summaries:
                    - team_abbr: PIT
                      first_year: 2007
                      last_year: 2025
                      stadium_names: Acrisure Stadium
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/reference/officials/{official_key}:
    get:
      tags:
        - Reference
      summary: Get raw official record
      description: Returns the table-shaped raw official row for one official key, including parsed raw_row data when present.
      operationId: getReferenceOfficial
      parameters:
        - $ref: "#/components/parameters/officialKey"
      responses:
        "200":
          description: Raw official record
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/ReferenceOfficialRecord"
              example:
                data:
                  official_key: clete-blakeman
                  display_name: Clete Blakeman
                  first_year: 2008
                  last_year: 2025
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/reference/officials/{official_key}/{field}:
    get:
      tags:
        - Reference
      summary: Get one raw official field
      description: Returns a single field from the raw official record.
      operationId: getReferenceOfficialField
      parameters:
        - $ref: "#/components/parameters/officialKey"
        - name: field
          in: path
          required: true
          description: Field name from the raw official record.
          schema:
            type: string
          example: display_name
      responses:
        "200":
          description: Raw official field value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: display_name
                  value: Clete Blakeman
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/reference/venues/{venue_key}:
    get:
      tags:
        - Reference
      summary: Get raw venue record
      description: Returns the table-shaped raw venue row for one venue key, including parsed raw_row data when present.
      operationId: getReferenceVenue
      parameters:
        - $ref: "#/components/parameters/venueKey"
      responses:
        "200":
          description: Raw venue record
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/ReferenceVenueRecord"
              example:
                data:
                  venue_key: m-t-bank-stadium
                  venue_name: M&T Bank Stadium
                  city: Baltimore
                  state: MD
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/reference/venues/{venue_key}/{field}:
    get:
      tags:
        - Reference
      summary: Get one raw venue field
      description: Returns a single field from the raw venue record.
      operationId: getReferenceVenueField
      parameters:
        - $ref: "#/components/parameters/venueKey"
        - name: field
          in: path
          required: true
          description: Field name from the raw venue record.
          schema:
            type: string
          example: venue_name
      responses:
        "200":
          description: Raw venue field value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: venue_name
                  value: M&T Bank Stadium
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/show:
    get:
      tags:
        - Metadata
      summary: Get API metadata payload
      operationId: getShowMetadata
      responses:
        "200":
          description: Top-level metadata payload
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    properties:
                      summary:
                        type:
                          - string
                          - "null"
                      tagline:
                        type:
                          - string
                          - "null"
                      studio:
                        type:
                          - string
                          - "null"
                      network:
                        type:
                          - string
                          - "null"
                      content_rating:
                        type:
                          - string
                          - "null"
                      art_path:
                        type:
                          - string
                          - "null"
                      art_url:
                        type:
                          - string
                          - "null"
              example:
                data:
                  summary: Historical NFL data platform and API.
                  tagline: Football intelligence, built for speed.
                  studio: SportDBX
                  network: NFLMeta
                  content_rating: TV-G
                  art_path: /brand/hero.png
                  art_url: https://nflmeta.org/brand/hero.png
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "401": *a5
        "404": &a6
          $ref: "#/components/responses/NotFound"
  /api/v1/season/{year}:
    get:
      tags:
        - Seasons
      summary: Get season summary by year
      operationId: getSeasonSummary
      parameters:
        - name: year
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          example: 2025
      responses:
        "200":
          description: Season summary record
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    properties:
                      season_year:
                        type: integer
                      super_bowl:
                        type:
                          - string
                          - "null"
                      winner:
                        type:
                          - string
                          - "null"
                      runner_up:
                        type:
                          - string
                          - "null"
                      final_score:
                        type:
                          - string
                          - "null"
                      mvp:
                        type:
                          - string
                          - "null"
                      summary:
                        type:
                          - string
                          - "null"
              example:
                data:
                  season_year: 2025
                  super_bowl: Super Bowl LX
                  winner: null
                  runner_up: null
                  final_score: null
                  mvp: null
                  summary: Championship summary pending final game results.
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400": &a7
          $ref: "#/components/responses/BadRequest"
        "401": *a5
        "404": *a6
  /api/v1/season/{year}/{field}:
    get:
      tags:
        - Seasons
      summary: Get one season summary field
      description: Returns a single field from the main season summary payload. Supported fields include season_year, super_bowl, winner, runner_up, final_score, mvp, and summary.
      operationId: getSeasonSummaryField
      parameters:
        - name: year
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          example: 2025
        - name: field
          in: path
          required: true
          schema:
            type: string
          example: winner
      responses:
        "200":
          description: Season summary field value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldValueResponse"
              example:
                data:
                  field: winner
                  value: Kansas City Chiefs
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/byes/{year}:
    get:
      tags:
        - Seasons
      summary: Get bye weeks by season year
      operationId: getByeWeeks
      parameters:
        - name: year
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          example: 2025
      responses:
        "200":
          description: Bye week assignments
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    properties:
                      season_year:
                        type: integer
                      byes:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            abbr:
                              type: string
                            city:
                              type:
                                - string
                                - "null"
                            nickname:
                              type:
                                - string
                                - "null"
                            full_name:
                              type:
                                - string
                                - "null"
                            bye_week:
                              type: integer
                            bye_weeks:
                              type: array
                              items:
                                type: integer
              example:
                data:
                  season_year: 2025
                  byes:
                    - id: 24
                      abbr: PIT
                      city: Pittsburgh
                      nickname: Steelers
                      full_name: Pittsburgh Steelers
                      bye_week: 9
                      bye_weeks:
                        - 9
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
        "400": *a7
        "401": *a5
        "404": *a6
  /api/v1/health:
    get:
      tags:
        - Operations
      summary: Service health status
      operationId: getHealth
      security: []
      responses:
        "200":
          description: Service is reachable
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                      db:
                        type: boolean
              example:
                data:
                  status: ok
                  db: true
  /api/v1/usage:
    get:
      tags:
        - Usage
      summary: Get current API key usage and quota
      operationId: getUsage
      responses:
        "200":
          description: Usage and quota snapshot for authenticated API key
          headers:
            X-RateLimit-Limit: *a1
            X-RateLimit-Remaining: *a2
            X-RateLimit-Reset: *a3
            X-RateLimit-Policy: *a4
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    properties:
                      api_key_id:
                        type: integer
                      request_count:
                        type: integer
                        description: Current month request count
                      quota_limit:
                        type: integer
                      quota_remaining:
                        type: integer
                      quota_reset_at:
                        type: string
                        format: date-time
                      policy:
                        type: string
                      lifetime_request_count:
                        type: integer
                        description: All-time request count for this key
                      billing_plan:
                        type: string
                        example: pro
                      quota_source:
                        type: string
                        enum:
                          - plan
                          - override
              example:
                data:
                  api_key_id: 42
                  request_count: 158
                  quota_limit: 50000
                  quota_remaining: 49842
                  quota_reset_at: 2026-04-01T00:00:00.000Z
                  policy: monthly
                  lifetime_request_count: 10742
                  billing_plan: pro
                  quota_source: plan
        "401":
          $ref: "#/components/responses/Unauthorized"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-NFLMeta-Key
  parameters:
    gameId:
      name: id
      in: path
      required: true
      description: Canonical game id used by NFLMeta. You can get it from /api/v1/games or /api/v1/playoff-games list endpoints.
      schema:
        type: integer
        minimum: 1
      example: 12001
    teamAbbr:
      name: abbr
      in: path
      required: true
      description: Team abbreviation such as PIT, DAL, or SF.
      schema:
        type: string
        minLength: 2
        maxLength: 5
      example: PIT
    playerKey:
      name: player_key
      in: path
      required: true
      description: Stable player key used by NFLMeta, such as a GSIS-based key.
      schema:
        type: string
      example: gsis:00-0034857
    coachKey:
      name: coach_key
      in: path
      required: true
      description: Stable coach key used by NFLMeta.
      schema:
        type: string
      example: mike-tomlin
    officialKey:
      name: official_key
      in: path
      required: true
      description: Stable official key used by NFLMeta.
      schema:
        type: string
      example: clete-blakeman
    venueKey:
      name: venue_key
      in: path
      required: true
      description: Stable venue key used by NFLMeta.
      schema:
        type: string
      example: m-t-bank-stadium
    limit:
      name: limit
      in: query
      description: Maximum number of rows to return in one response.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 50
      example: 50
    offset:
      name: offset
      in: query
      description: Number of rows to skip before returning results. Use with limit for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
      example: 0
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
      example:
        error:
          code: unauthorized
          message: invalid api key
    FieldValueResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - field
            - value
          properties:
            field:
              type: string
            value: {}
    CoachIdentity:
      type: object
      properties:
        coach_key:
          type: string
        display_name:
          type:
            - string
            - "null"
        source_name:
          type:
            - string
            - "null"
        photo_path:
          type:
            - string
            - "null"
        hall_of_fame:
          type:
            - boolean
            - "null"
        rank:
          type:
            - integer
            - "null"
    CoachBio:
      type: object
      properties:
        birth_date:
          type:
            - string
            - "null"
        birth_place:
          type:
            - string
            - "null"
        death_date:
          type:
            - string
            - "null"
        death_place:
          type:
            - string
            - "null"
        college_name:
          type:
            - string
            - "null"
        playing_position:
          type:
            - string
            - "null"
        bio_summary:
          type:
            - string
            - "null"
        did_you_know:
          type:
            - string
            - "null"
        playing_career_summary:
          type:
            - string
            - "null"
        playing_college_years:
          type:
            - string
            - "null"
        pro_football_hall_of_fame_year:
          type:
            - integer
            - "null"
        playing_nfl_years:
          type:
            - string
            - "null"
        playing_nfl_teams:
          type:
            - string
            - "null"
        played_in_nfl:
          type:
            - boolean
            - "null"
    CoachCareer:
      type: object
      properties:
        first_year:
          type:
            - integer
            - "null"
        last_year:
          type:
            - integer
            - "null"
        years_total:
          type:
            - integer
            - "null"
        regular_games:
          type:
            - integer
            - "null"
        regular_wins:
          type:
            - integer
            - "null"
        regular_losses:
          type:
            - integer
            - "null"
        regular_ties:
          type:
            - integer
            - "null"
        regular_win_pct:
          type:
            - string
            - number
            - "null"
        playoff_years:
          type:
            - integer
            - "null"
        playoff_games:
          type:
            - integer
            - "null"
        playoff_wins:
          type:
            - integer
            - "null"
        playoff_losses:
          type:
            - integer
            - "null"
        playoff_win_pct:
          type:
            - string
            - number
            - "null"
        championships:
          type:
            - integer
            - "null"
        super_bowls:
          type:
            - integer
            - "null"
        conference_titles:
          type:
            - integer
            - "null"
        average_rank:
          type:
            - string
            - number
            - "null"
        best_rank:
          type:
            - integer
            - "null"
    CoachHistoryEntry:
      type: object
      properties:
        id:
          type: integer
        team_id:
          type:
            - integer
            - "null"
        season_year:
          type: integer
        head_coach:
          type: string
        is_interim:
          type:
            - boolean
            - "null"
        start_week:
          type:
            - integer
            - "null"
        end_week:
          type:
            - integer
            - "null"
        team_abbr:
          type:
            - string
            - "null"
        team_name:
          type:
            - string
            - "null"
        photo_path:
          type:
            - string
            - "null"
    CoachAwardSummary:
      type: object
      properties:
        award_name:
          type: string
        award_count:
          type: integer
        first_year:
          type:
            - integer
            - "null"
        last_year:
          type:
            - integer
            - "null"
    CoachTeamRecord:
      type: object
      properties:
        team_id:
          type:
            - integer
            - "null"
        team_abbr:
          type:
            - string
            - "null"
        team_name:
          type:
            - string
            - "null"
        first_year:
          type: integer
        last_year:
          type: integer
        is_interim:
          type: boolean
        games_played:
          type:
            - integer
            - "null"
        wins:
          type:
            - integer
            - "null"
        losses:
          type:
            - integer
            - "null"
        ties:
          type:
            - integer
            - "null"
        playoff_games:
          type:
            - integer
            - "null"
        playoff_wins:
          type:
            - integer
            - "null"
        playoff_losses:
          type:
            - integer
            - "null"
    CoachStadiumSummary:
      type: object
      properties:
        team_id:
          type:
            - integer
            - "null"
        team_abbr:
          type:
            - string
            - "null"
        team_name:
          type:
            - string
            - "null"
        first_year:
          type: integer
        last_year:
          type: integer
        is_interim:
          type: boolean
        stadium_names:
          type:
            - string
            - "null"
        stadium_logo_paths:
          type:
            - string
            - "null"
    CoachHistory:
      type: object
      properties:
        history:
          type: array
          items:
            $ref: "#/components/schemas/CoachHistoryEntry"
        awards:
          type: array
          items:
            $ref: "#/components/schemas/CoachAwardSummary"
        team_records:
          type: array
          items:
            $ref: "#/components/schemas/CoachTeamRecord"
        stadium_summaries:
          type: array
          items:
            $ref: "#/components/schemas/CoachStadiumSummary"
    CoachProfile:
      type: object
      properties:
        identity:
          $ref: "#/components/schemas/CoachIdentity"
        bio:
          $ref: "#/components/schemas/CoachBio"
        career:
          $ref: "#/components/schemas/CoachCareer"
        history:
          $ref: "#/components/schemas/CoachHistory"
    ReferenceCoachRecord:
      type: object
      properties:
        coach_key:
          type: string
        display_name:
          type:
            - string
            - "null"
        source_name:
          type:
            - string
            - "null"
        first_year:
          type:
            - integer
            - "null"
        last_year:
          type:
            - integer
            - "null"
        raw_row: {}
    ReferenceOfficialRecord:
      type: object
      properties:
        official_key:
          type: string
        display_name:
          type:
            - string
            - "null"
        first_year:
          type:
            - integer
            - "null"
        last_year:
          type:
            - integer
            - "null"
        positions:
          type:
            - array
            - "null"
          items:
            type: string
        raw_row: {}
    ReferenceVenueRecord:
      type: object
      properties:
        venue_key:
          type: string
        venue_name:
          type:
            - string
            - "null"
        city:
          type:
            - string
            - "null"
        state:
          type:
            - string
            - "null"
        first_year:
          type:
            - integer
            - "null"
        last_year:
          type:
            - integer
            - "null"
        raw_row: {}
    ListMeta:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        returned:
          type: integer
        has_more:
          type: boolean
    Team:
      type: object
      properties:
        id:
          type: integer
        abbr:
          type: string
        city:
          type:
            - string
            - "null"
        nickname:
          type:
            - string
            - "null"
        fullName:
          type:
            - string
            - "null"
        conference:
          type:
            - string
            - "null"
        division:
          type:
            - string
            - "null"
        gameCount:
          type: integer
    Season:
      type: object
      properties:
        id:
          type: integer
        year:
          type: integer
        gameCount:
          type: integer
    TeamProfile:
      type: object
      properties:
        team:
          $ref: "#/components/schemas/Team"
        seasonYear:
          type: integer
        seasonYears:
          type: array
          items:
            type: integer
        displayName:
          type: string
        record:
          type:
            - object
            - "null"
          properties:
            wins:
              type: integer
            losses:
              type: integer
            ties:
              type: integer
            gamesPlayed:
              type: integer
    TeamProfileExtras:
      type: object
      properties:
        offense:
          type: array
          items:
            $ref: "#/components/schemas/ProfileStat"
        defense:
          type: array
          items:
            $ref: "#/components/schemas/ProfileStat"
        specialTeams:
          type: array
          items:
            $ref: "#/components/schemas/ProfileStat"
        powerRankings:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              rank:
                type: integer
              sourceUrl:
                type:
                  - string
                  - "null"
              updatedAt:
                type:
                  - string
                  - "null"
        stadium:
          type:
            - object
            - "null"
          properties:
            name:
              type: string
            location:
              type:
                - string
                - "null"
            capacity:
              type:
                - integer
                - "null"
            surface:
              type:
                - string
                - "null"
            inauguralDate:
              type:
                - string
                - "null"
            logoUrl:
              type:
                - string
                - "null"
        proBowl:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              position:
                type:
                  - string
                  - "null"
              headshotUrl:
                type:
                  - string
                  - "null"
              isReplacement:
                type: boolean
              college:
                type:
                  - string
                  - "null"
              heightIn:
                type:
                  - integer
                  - "null"
              weightLb:
                type:
                  - integer
                  - "null"
              draftYear:
                type:
                  - integer
                  - "null"
              draftRound:
                type:
                  - string
                  - "null"
              draftPick:
                type:
                  - string
                  - "null"
              draftTeam:
                type:
                  - string
                  - "null"
              yearsPro:
                type:
                  - string
                  - "null"
              birthPlace:
                type:
                  - string
                  - "null"
              stats:
                type: array
                items:
                  $ref: "#/components/schemas/ProfileStat"
    ProfileStat:
      type: object
      properties:
        label:
          type: string
        value:
          type: string
    GameListItem:
      type: object
      properties:
        id:
          type: integer
        isPlayoff:
          type: boolean
        seasonYear:
          type: integer
        week:
          type:
            - integer
            - "null"
        round:
          type:
            - string
            - "null"
        gameDate:
          type: string
        kickoffAt:
          type:
            - string
            - "null"
        awayAbbr:
          type: string
        awayName:
          type: string
        homeAbbr:
          type: string
        homeName:
          type: string
        awayScore:
          type:
            - integer
            - "null"
        homeScore:
          type:
            - integer
            - "null"
        broadcastNetwork:
          type:
            - string
            - "null"
        stadium:
          type:
            - string
            - "null"
    TeamReference:
      type: object
      properties:
        id:
          type: integer
        abbr:
          type: string
        city:
          type:
            - string
            - "null"
        nickname:
          type:
            - string
            - "null"
        full_name:
          type:
            - string
            - "null"
    CoachReference:
      type: object
      properties:
        name:
          type:
            - string
            - "null"
        photo_path:
          type:
            - string
            - "null"
    GameDetail:
      type: object
      properties:
        id:
          type: integer
        season_year:
          type: integer
        week:
          type:
            - integer
            - "null"
        round:
          type:
            - string
            - "null"
        game_date:
          type: string
        kickoff_at:
          type:
            - string
            - "null"
        title:
          type:
            - string
            - "null"
        away_team:
          $ref: "#/components/schemas/TeamReference"
        home_team:
          $ref: "#/components/schemas/TeamReference"
        away_coach:
          $ref: "#/components/schemas/CoachReference"
        home_coach:
          $ref: "#/components/schemas/CoachReference"
        away_score:
          type:
            - integer
            - "null"
        home_score:
          type:
            - integer
            - "null"
        stadium:
          type:
            - string
            - "null"
        broadcast_network:
          type:
            - string
            - "null"
        announcers:
          type:
            - string
            - "null"
        summary:
          type:
            - string
            - "null"
        is_playoff:
          type:
            - boolean
            - "null"
    GameExtras:
      type: object
      properties:
        teamStats:
          type:
            - object
            - "null"
          additionalProperties: true
        expectedPoints:
          type:
            - object
            - "null"
          additionalProperties: true
        gameInfo:
          type: array
          items:
            type: object
            properties:
              info:
                type: string
              stat:
                type: string
        officials:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
              name:
                type: string
        homeStarters:
          type: array
          items:
            type: object
            properties:
              pos:
                type: string
              player:
                type: string
        awayStarters:
          type: array
          items:
            type: object
            properties:
              pos:
                type: string
              player:
                type: string
        stadiumMeta:
          type:
            - object
            - "null"
          properties:
            name:
              type: string
            capacity:
              type:
                - integer
                - "null"
            surface:
              type:
                - string
                - "null"
            location:
              type:
                - string
                - "null"
            inauguralDate:
              type:
                - string
                - "null"
            logoUrl:
              type:
                - string
                - "null"
    StandingsPayload:
      type: object
      properties:
        seasonYear:
          type: integer
        seasonYears:
          type: array
          items:
            type: integer
        grouped:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: array
              items:
                type: object
                properties:
                  teamId:
                    type: integer
                  teamAbbr:
                    type: string
                  teamName:
                    type: string
                  conference:
                    type: string
                  division:
                    type: string
                  wins:
                    type: integer
                  losses:
                    type: integer
                  ties:
                    type: integer
                  gamesPlayed:
                    type: integer
    PlayoffPicturePayload:
      type: object
      properties:
        seasonYear:
          type: integer
        seasonYears:
          type: array
          items:
            type: integer
        rounds:
          type: object
          additionalProperties:
            type: object
            properties:
              afc:
                type: array
                items:
                  $ref: "#/components/schemas/PlayoffMatch"
              nfc:
                type: array
                items:
                  $ref: "#/components/schemas/PlayoffMatch"
              other:
                type: array
                items:
                  $ref: "#/components/schemas/PlayoffMatch"
    PlayoffMatch:
      type: object
      properties:
        id:
          type: integer
        seasonYear:
          type: integer
        round:
          type: string
        conference:
          type: string
        gameDate:
          type:
            - string
            - "null"
        awayName:
          type: string
        homeName:
          type: string
        awayScore:
          type:
            - integer
            - "null"
        homeScore:
          type:
            - integer
            - "null"
    SuperBowlItem:
      type: object
      properties:
        id:
          type:
            - integer
            - "null"
        seasonYear:
          type: integer
        gameDate:
          type:
            - string
            - "null"
        title:
          type: string
        homeName:
          type: string
        awayName:
          type: string
        homeScore:
          type:
            - integer
            - "null"
        awayScore:
          type:
            - integer
            - "null"
        winnerName:
          type:
            - string
            - "null"
        isPlaceholder:
          type: boolean
    SuperBowlTeamRecord:
      type: object
      properties:
        teamAbbr:
          type: string
        teamName:
          type: string
        wins:
          type: integer
        appearances:
          type: integer
        games:
          type: array
          items:
            $ref: "#/components/schemas/SuperBowlItem"
    StadiumHistoryItem:
      type: object
      properties:
        id:
          type: integer
        teamId:
          type: integer
        teamAbbr:
          type: string
        teamName:
          type: string
        stadiumName:
          type: string
        startYear:
          type: integer
        endYear:
          type:
            - integer
            - "null"
        inauguralDate:
          type:
            - string
            - "null"
        logoPath:
          type:
            - string
            - "null"
    TeamLogoHistoryItem:
      type: object
      properties:
        id:
          type: integer
        teamId:
          type: integer
        teamAbbr:
          type: string
        teamName:
          type: string
        startYear:
          type: integer
        endYear:
          type:
            - integer
            - "null"
        logoName:
          type:
            - string
            - "null"
        logoUrl:
          type:
            - string
            - "null"
        source:
          type: string
    SeasonsListResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Season"
        meta:
          $ref: "#/components/schemas/ListMeta"
    TeamsListResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Team"
        meta:
          $ref: "#/components/schemas/ListMeta"
    GamesListResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/GameListItem"
        meta:
          allOf:
            - $ref: "#/components/schemas/ListMeta"
            - type: object
              properties:
                order:
                  type: string
                include_playoffs:
                  type: boolean
    SuperBowlsListResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SuperBowlItem"
        meta:
          $ref: "#/components/schemas/ListMeta"
    StadiumHistoryResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/StadiumHistoryItem"
        meta:
          $ref: "#/components/schemas/ListMeta"
    TeamLogoHistoryResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/TeamLogoHistoryItem"
        meta:
          $ref: "#/components/schemas/ListMeta"
