openapi: 3.1.0
info:
  title: Statorium American Football Games 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/
servers:
- url: https://api.statorium.com/api/v1
  description: Statorium API Server
security:
- apiKey: []
tags:
- name: Games
  description: Access NFL game data including live scores, results, and schedules.
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'
  /basketball/games/:
    get:
      operationId: listBasketballGames
      summary: List Basketball Games
      description: Returns basketball games filtered by league, season, team, or date. Includes live, scheduled, and completed games with scores.
      tags:
      - Games
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - name: leagueId
        in: query
        required: false
        schema:
          type: integer
        description: Filter games by league ID.
      - name: date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter games by date (YYYY-MM-DD).
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - live
          - scheduled
          - finished
        description: Filter games by status.
      responses:
        '200':
          description: List of games
          content:
            application/json:
              schema:
                type: object
                properties:
                  games:
                    type: array
                    items:
                      $ref: '#/components/schemas/Game_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /basketball/games/{gameId}/:
    get:
      operationId: getBasketballGame
      summary: Get Basketball Game
      description: Returns full details for a specific basketball game including quarter scores, box score statistics, and lineups.
      tags:
      - Games
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - name: gameId
        in: path
        required: true
        schema:
          type: integer
        description: The unique game identifier.
      responses:
        '200':
          description: Game details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GameDetail_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PlayerGameStats:
      type: object
      description: Player statistics for a single game.
      properties:
        playerId:
          type: integer
        name:
          type: string
        teamId:
          type: integer
        points:
          type: integer
        rebounds:
          type: integer
        assists:
          type: integer
        steals:
          type: integer
        blocks:
          type: integer
        turnovers:
          type: integer
        minutesPlayed:
          type: string
        fieldGoalsMade:
          type: integer
        fieldGoalsAttempted:
          type: integer
        threePointersMade:
          type: integer
        threePointersAttempted:
          type: integer
        freeThrowsMade:
          type: integer
        freeThrowsAttempted:
          type: integer
    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'
    Game_2:
      type: object
      description: A basketball game with score and status.
      properties:
        id:
          type: integer
        homeTeam:
          $ref: '#/components/schemas/TeamRef_2'
        awayTeam:
          $ref: '#/components/schemas/TeamRef_2'
        homeScore:
          type: integer
        awayScore:
          type: integer
        status:
          type: string
          enum:
          - live
          - scheduled
          - finished
        gameDate:
          type: string
          format: date-time
        quarter:
          type: integer
          description: Current quarter for live games.
        timeRemaining:
          type: string
          description: Time remaining in the current quarter.
    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.
    TeamRef:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        abbreviation:
          type: string
    TeamRef_2:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    GameDetail_2:
      allOf:
      - $ref: '#/components/schemas/Game_2'
      - type: object
        properties:
          quarterScores:
            type: array
            items:
              type: object
              properties:
                quarter:
                  type: integer
                homeScore:
                  type: integer
                awayScore:
                  type: integer
          playerStats:
            type: array
            items:
              $ref: '#/components/schemas/PlayerGameStats'
    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
  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
  parameters:
    ApiKeyParam:
      name: apikey
      in: query
      required: true
      schema:
        type: string
      description: Your Statorium API token.
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: apikey
      description: API token provided upon subscription purchase.
externalDocs:
  description: Statorium API Documentation
  url: https://statorium.com/stats-api-documentation