openapi: 3.1.0
info:
  title: Statorium American Football API
  description: >-
    The Statorium American Football API provides NFL data including live
    game scores, schedules, player news, team statistics, rosters, and
    historical records. The API delivers unique daily news feeds linked to
    NFL players and teams along with game data in JSON format. Coverage
    includes all NFL teams and games for current and past seasons.
  version: '1.0.0'
  contact:
    name: Statorium Support
    url: https://statorium.com/
  termsOfService: https://statorium.com/
externalDocs:
  description: Statorium API Documentation
  url: https://statorium.com/stats-api-documentation
servers:
  - url: https://api.statorium.com/api/v1
    description: Statorium API Server
tags:
  - name: Games
    description: Access NFL game data including live scores, results, and schedules.
  - name: Teams
    description: Retrieve NFL team information, rosters, and statistics.
  - name: Players
    description: Access NFL player profiles, news, and statistics.
  - name: Standings
    description: Retrieve AFC and NFC standings.
  - name: News
    description: Access daily news feeds for NFL players and teams.
security:
  - apiKey: []
paths:
  /nfl/games/:
    get:
      operationId: listNflGames
      summary: List NFL Games
      description: >-
        Returns NFL games filtered by week, season, team, or date with
        live scores, schedules, and completed results.
      tags:
        - Games
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: week
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 22
          description: NFL week number (1-22 including playoffs).
        - name: season
          in: query
          required: false
          schema:
            type: integer
          description: NFL season year (e.g., 2025).
        - name: teamId
          in: query
          required: false
          schema:
            type: integer
          description: Filter games involving a specific team.
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - live
              - scheduled
              - finished
          description: Filter games by status.
      responses:
        '200':
          description: List of NFL games
          content:
            application/json:
              schema:
                type: object
                properties:
                  games:
                    type: array
                    items:
                      $ref: '#/components/schemas/Game'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /nfl/games/{gameId}/:
    get:
      operationId: getNflGame
      summary: Get NFL Game
      description: >-
        Returns full details for a specific NFL game including quarter scores,
        team statistics, and play summaries.
      tags:
        - Games
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: gameId
          in: path
          required: true
          schema:
            type: integer
          description: The unique game identifier.
      responses:
        '200':
          description: NFL game details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GameDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /nfl/teams/:
    get:
      operationId: listNflTeams
      summary: List NFL Teams
      description: >-
        Returns all 32 NFL teams with names, divisions, conference, and
        logo URLs.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: conference
          in: query
          required: false
          schema:
            type: string
            enum:
              - AFC
              - NFC
          description: Filter teams by conference.
        - name: division
          in: query
          required: false
          schema:
            type: string
            enum:
              - East
              - West
              - North
              - South
          description: Filter teams by division.
      responses:
        '200':
          description: List of NFL teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  teams:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /nfl/teams/{teamId}/:
    get:
      operationId: getNflTeam
      summary: Get NFL Team
      description: >-
        Returns detailed information about an NFL team including roster,
        season record, and team metadata.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: teamId
          in: path
          required: true
          schema:
            type: integer
          description: The unique team identifier.
      responses:
        '200':
          description: NFL team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /nfl/players/{playerId}/:
    get:
      operationId: getNflPlayer
      summary: Get NFL Player
      description: >-
        Returns detailed information about an NFL player including profile,
        career stats, and current season statistics.
      tags:
        - Players
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: playerId
          in: path
          required: true
          schema:
            type: integer
          description: The unique player identifier.
      responses:
        '200':
          description: NFL player details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Player'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /nfl/standings/:
    get:
      operationId: getNflStandings
      summary: Get NFL Standings
      description: >-
        Returns AFC and NFC standings including division rankings, win/loss
        records, and tiebreaker information.
      tags:
        - Standings
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: season
          in: query
          required: false
          schema:
            type: integer
          description: Season year (defaults to current season).
      responses:
        '200':
          description: NFL standings
          content:
            application/json:
              schema:
                type: object
                properties:
                  standings:
                    type: array
                    items:
                      $ref: '#/components/schemas/StandingEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /nfl/news/:
    get:
      operationId: listNflNews
      summary: List NFL News
      description: >-
        Returns the latest NFL news articles and updates linked to players
        and teams. Includes injuries, transactions, game previews, and
        analysis.
      tags:
        - News
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: teamId
          in: query
          required: false
          schema:
            type: integer
          description: Filter news by team ID.
        - name: playerId
          in: query
          required: false
          schema:
            type: integer
          description: Filter news by player ID.
        - name: count
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          description: Number of news items to return.
      responses:
        '200':
          description: List of NFL news articles
          content:
            application/json:
              schema:
                type: object
                properties:
                  news:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: apikey
      description: API token provided upon subscription purchase.
  parameters:
    ApiKeyParam:
      name: apikey
      in: query
      required: true
      schema:
        type: string
      description: Your Statorium API token.
  schemas:
    Game:
      type: object
      description: An NFL game.
      properties:
        id:
          type: integer
        homeTeam:
          $ref: '#/components/schemas/TeamRef'
        awayTeam:
          $ref: '#/components/schemas/TeamRef'
        homeScore:
          type: integer
        awayScore:
          type: integer
        status:
          type: string
          enum:
            - live
            - scheduled
            - finished
        gameDate:
          type: string
          format: date-time
        week:
          type: integer
          description: NFL week number.
        season:
          type: integer
          description: NFL season year.
        quarter:
          type: string
          description: Current quarter or game period for live games.
        timeRemaining:
          type: string
          description: Time remaining in the current period.
    GameDetail:
      allOf:
        - $ref: '#/components/schemas/Game'
        - type: object
          properties:
            quarterScores:
              type: array
              items:
                type: object
                properties:
                  quarter:
                    type: string
                  homeScore:
                    type: integer
                  awayScore:
                    type: integer
            teamStats:
              type: object
              properties:
                home:
                  $ref: '#/components/schemas/TeamGameStats'
                away:
                  $ref: '#/components/schemas/TeamGameStats'
    TeamRef:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        abbreviation:
          type: string
    Team:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        city:
          type: string
        abbreviation:
          type: string
        conference:
          type: string
          enum:
            - AFC
            - NFC
        division:
          type: string
          enum:
            - East
            - West
            - North
            - South
        logoUrl:
          type: string
          format: uri
        stadium:
          type: string
    Player:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        position:
          type: string
        teamId:
          type: integer
        jerseyNumber:
          type: integer
        college:
          type: string
        experience:
          type: integer
          description: Years of NFL experience.
        status:
          type: string
          enum:
            - active
            - injured
            - practice_squad
            - free_agent
    TeamGameStats:
      type: object
      description: Team statistics for a single NFL game.
      properties:
        totalYards:
          type: integer
        rushingYards:
          type: integer
        passingYards:
          type: integer
        firstDowns:
          type: integer
        turnovers:
          type: integer
        penalties:
          type: integer
        penaltyYards:
          type: integer
        timeOfPossession:
          type: string
        thirdDownConversions:
          type: string
        redZoneConversions:
          type: string
    StandingEntry:
      type: object
      properties:
        position:
          type: integer
        team:
          $ref: '#/components/schemas/TeamRef'
        conference:
          type: string
        division:
          type: string
        wins:
          type: integer
        losses:
          type: integer
        ties:
          type: integer
        winPercentage:
          type: number
        pointsFor:
          type: integer
        pointsAgainst:
          type: integer
    NewsItem:
      type: object
      description: An NFL news article or update.
      properties:
        id:
          type: integer
        headline:
          type: string
        body:
          type: string
        publishedAt:
          type: string
          format: date-time
        teamId:
          type: integer
        playerId:
          type: integer
        category:
          type: string
          enum:
            - injury
            - transaction
            - preview
            - recap
            - analysis
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string