openapi: 3.1.0
info:
  title: PickGPT NFL Data API
  version: 1.1.0
  description: Automated schedule, Yahoo public pick distribution, injuries, odds, weather, results, and rolling team metrics for PickGPT.
  license:
    name: PickGPT data terms
    url: https://craigcarroll.design/picks/license.html
servers:
  - url: https://craigcarroll.design/wp-json/pickgpt/v1
security: []
paths:
  /current:
    get:
      operationId: getCurrentWeekData
      summary: Get the complete current NFL Pick'em week dataset
      description: Call this first for every current-week prediction request. It includes Yahoo order and public lean, schedule, injuries, matchup context, and rolling metrics.
      responses:
        '200':
          description: Current weekly data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeekData'
        '404':
          $ref: '#/components/responses/NotFound'
  /season/{season}/week/{week}:
    get:
      operationId: getWeekData
      summary: Get one specified NFL week
      parameters:
        - name: season
          in: path
          required: true
          description: Four-digit NFL season year, such as 2026
          schema: { type: integer, minimum: 2026, maximum: 2026 }
        - name: week
          in: path
          required: true
          description: NFL week number
          schema: { type: integer, minimum: 1, maximum: 22 }
      responses:
        '200':
          description: Requested weekly data, if it has been generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeekData'
        '404':
          $ref: '#/components/responses/NotFound'
  /season/{season}/schedule:
    get:
      operationId: getSeasonSchedule
      summary: Get a compact NFL season schedule with matchups, scores, and venues
      parameters:
        - name: season
          in: path
          required: true
          schema: { type: integer, minimum: 2026, maximum: 2026 }
      responses:
        '200':
          description: Season schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeasonSchedule'
        '404':
          $ref: '#/components/responses/NotFound'
  /season/{season}/teams/{team}/roster:
    get:
      operationId: getTeamRoster
      summary: Get the latest published roster for one NFL team
      parameters:
        - name: season
          in: path
          required: true
          schema: { type: integer, minimum: 2026, maximum: 2026 }
        - name: team
          in: path
          required: true
          description: Uppercase nflverse team abbreviation, such as BUF, KC, LA, LAC, or WAS
          schema: { type: string, pattern: '^[A-Z]{2,3}$' }
      responses:
        '200':
          description: Latest roster snapshot for the requested team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamRoster'
        '404':
          $ref: '#/components/responses/NotFound'
  /health:
    get:
      operationId: getPickGptDataHealth
      summary: Check data freshness and source warnings
      responses:
        '200':
          description: Feed health
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedHealth'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: Requested generated data is unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      required: [code, message, data]
      properties:
        code: { type: string }
        message: { type: string }
        data:
          type: object
          required: [status]
          properties:
            status: { type: integer }
    WeekData:
      type: object
      required: [season, week, updatedAt, games, warnings]
      properties:
        season: { type: integer }
        seasonLabel: { type: string }
        week: { type: integer }
        updatedAt: { type: string, format: date-time }
        warnings:
          type: array
          items: { type: string }
        games:
          type: array
          items:
            $ref: '#/components/schemas/WeekGame'
    WeekGame:
      type: object
      required: [yahooOrder, gameId, week, gameType]
      properties:
        yahooOrder: { type: integer }
        gameId: { type: string }
        week: { type: integer }
        gameType: { type: string }
      additionalProperties: true
    SeasonSchedule:
      type: object
      required: [season, updatedAt, games]
      properties:
        season: { type: integer }
        updatedAt: { type: string, format: date-time }
        games:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleGame'
    ScheduleGame:
      type: object
      required: [game_id, season, game_type, week, gameday, away_team, home_team]
      properties:
        game_id: { type: string }
        season: { type: integer }
        game_type: { type: string }
        week: { type: integer }
        gameday: { type: string, format: date }
        weekday: { type: string }
        gametime: { type: [string, 'null'] }
        away_team: { type: string }
        away_score: { type: [number, 'null'] }
        home_team: { type: string }
        home_score: { type: [number, 'null'] }
        location: { type: string }
        result: { type: [number, 'null'] }
        total: { type: [number, 'null'] }
        overtime: { type: boolean }
        away_rest: { type: [integer, 'null'] }
        home_rest: { type: [integer, 'null'] }
        away_moneyline: { type: [number, 'null'] }
        home_moneyline: { type: [number, 'null'] }
        spread_line: { type: [number, 'null'] }
        total_line: { type: [number, 'null'] }
        div_game: { type: boolean }
        roof: { type: [string, 'null'] }
        surface: { type: [string, 'null'] }
        temp: { type: [number, 'null'] }
        wind: { type: [number, 'null'] }
        away_qb_name: { type: [string, 'null'] }
        home_qb_name: { type: [string, 'null'] }
        stadium: { type: [string, 'null'] }
      additionalProperties: true
    TeamRoster:
      type: object
      required: [season, rosterWeek, team, source, players]
      properties:
        season: { type: integer }
        rosterWeek: { type: integer }
        team: { type: string }
        source: { type: string, format: uri }
        players:
          type: array
          items:
            $ref: '#/components/schemas/RosterPlayer'
    RosterPlayer:
      type: object
      required: [team, position, full_name]
      properties:
        season: { type: [string, integer, 'null'] }
        team: { type: string }
        position: { type: [string, 'null'] }
        depth_chart_position: { type: [string, 'null'] }
        jersey_number: { type: [string, integer, 'null'] }
        status: { type: [string, 'null'] }
        full_name: { type: string }
        first_name: { type: [string, 'null'] }
        last_name: { type: [string, 'null'] }
        years_exp: { type: [string, integer, 'null'] }
        headshot_url: { type: [string, 'null'] }
      additionalProperties: true
    FeedHealth:
      type: object
      required: [status, season, week, rosterWeek, updatedAt, warnings]
      properties:
        status: { type: string, enum: [ok, degraded] }
        season: { type: integer }
        week: { type: integer }
        rosterWeek: { type: integer }
        updatedAt: { type: string, format: date-time }
        warnings:
          type: array
          items: { type: string }
