openapi: 3.1.0
info:
  title: Statorium Football API
  description: >-
    The Statorium Football API delivers comprehensive football/soccer data
    for over 200 leagues worldwide. The API provides live scores, match
    results, standings, fixtures, lineups, player and team statistics,
    head-to-head records, league logos, and translated player and team names.
    All responses are in JSON format and require an API token for
    authentication.
  version: '1.0.0'
  contact:
    name: Statorium Support
    url: https://statorium.com/
  termsOfService: https://statorium.com/
externalDocs:
  description: Statorium Football API Documentation
  url: https://statorium.com/stats-api-documentation
servers:
  - url: https://api.statorium.com/api/v1
    description: Statorium API Server
tags:
  - name: Leagues
    description: >-
      Access league listings, metadata, and configuration for all supported
      football leagues and competitions.
  - name: Seasons
    description: >-
      Retrieve season information, current and historical seasons for
      specific leagues.
  - name: Matches
    description: >-
      Access match data including live scores, results, schedules, lineups,
      and head-to-head information.
  - name: Teams
    description: >-
      Retrieve team data including squad information, statistics, and
      team metadata.
  - name: Players
    description: >-
      Access player data including profiles, statistics, and career
      information.
  - name: Standings
    description: >-
      Retrieve league standings and table data for current and past seasons.
security:
  - apiKey: []
paths:
  /leagues/:
    get:
      operationId: listLeagues
      summary: List All Leagues
      description: >-
        Returns all leagues the authenticated account has permission to access.
        Each league includes an ID, name, country, and optional logo URL.
      tags:
        - Leagues
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: List of accessible leagues
          content:
            application/json:
              schema:
                type: object
                properties:
                  leagues:
                    type: array
                    items:
                      $ref: '#/components/schemas/League'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /leagues/{leagueId}/:
    get:
      operationId: getLeague
      summary: Get League by ID
      description: >-
        Retrieves detailed information about a specific league including
        name, country, current season, and logo URL.
      tags:
        - Leagues
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: leagueId
          in: path
          required: true
          schema:
            type: integer
          description: The unique identifier of the league.
      responses:
        '200':
          description: League details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/League'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /seasons/:
    get:
      operationId: listSeasons
      summary: List All Seasons
      description: >-
        Returns all available seasons for the leagues accessible to the
        authenticated account.
      tags:
        - Seasons
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: leagueId
          in: query
          required: false
          schema:
            type: integer
          description: Filter seasons by league ID.
      responses:
        '200':
          description: List of seasons
          content:
            application/json:
              schema:
                type: object
                properties:
                  seasons:
                    type: array
                    items:
                      $ref: '#/components/schemas/Season'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /matches/:
    get:
      operationId: listMatches
      summary: List Matches
      description: >-
        Returns matches filtered by league, season, team, or date. Supports
        live score updates, scheduled fixtures, and completed results.
      tags:
        - Matches
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: leagueId
          in: query
          required: false
          schema:
            type: integer
          description: Filter matches by league ID.
        - name: seasonId
          in: query
          required: false
          schema:
            type: integer
          description: Filter matches by season ID.
        - name: teamId
          in: query
          required: false
          schema:
            type: integer
          description: Filter matches involving a specific team.
        - name: date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter matches by date (YYYY-MM-DD).
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - live
              - scheduled
              - finished
          description: Filter matches by status.
      responses:
        '200':
          description: List of matches
          content:
            application/json:
              schema:
                type: object
                properties:
                  matches:
                    type: array
                    items:
                      $ref: '#/components/schemas/Match'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /matches/{matchId}/:
    get:
      operationId: getMatch
      summary: Get Match by ID
      description: >-
        Retrieves full details for a specific match including score, lineups,
        events, statistics, and head-to-head history between the two teams.
      tags:
        - Matches
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: matchId
          in: path
          required: true
          schema:
            type: integer
          description: The unique identifier of the match.
      responses:
        '200':
          description: Match details with lineups and statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /teams/:
    get:
      operationId: listTeams
      summary: List Teams
      description: >-
        Returns teams filtered by league or season. Includes team name,
        country, logo, and founding information.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: leagueId
          in: query
          required: false
          schema:
            type: integer
          description: Filter teams by league ID.
        - name: seasonId
          in: query
          required: false
          schema:
            type: integer
          description: Filter teams by season ID.
      responses:
        '200':
          description: List of teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  teams:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /teams/{teamId}/:
    get:
      operationId: getTeam
      summary: Get Team by ID
      description: >-
        Retrieves detailed information about a specific team including squad,
        statistics, and season data.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: teamId
          in: path
          required: true
          schema:
            type: integer
          description: The unique identifier of the team.
      responses:
        '200':
          description: Team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /players/{playerId}/:
    get:
      operationId: getPlayer
      summary: Get Player by ID
      description: >-
        Retrieves detailed information about a specific player including
        profile, career history, and season statistics.
      tags:
        - Players
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: playerId
          in: path
          required: true
          schema:
            type: integer
          description: The unique identifier of the player.
      responses:
        '200':
          description: Player details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Player'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /standings/:
    get:
      operationId: getStandings
      summary: Get Standings
      description: >-
        Retrieves league standings table for a specific league and season
        including team position, points, wins, draws, losses, goals for,
        goals against, and goal difference.
      tags:
        - Standings
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: leagueId
          in: query
          required: true
          schema:
            type: integer
          description: The league ID for which to retrieve standings.
        - name: seasonId
          in: query
          required: false
          schema:
            type: integer
          description: The season ID (defaults to current season).
      responses:
        '200':
          description: League standings table
          content:
            application/json:
              schema:
                type: object
                properties:
                  standings:
                    type: array
                    items:
                      $ref: '#/components/schemas/StandingEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: apikey
      description: >-
        API token provided upon purchase of a data subscription. Include as
        query parameter in all requests.
  parameters:
    ApiKeyParam:
      name: apikey
      in: query
      required: true
      schema:
        type: string
      description: >-
        Your Statorium API token for authentication.
  schemas:
    League:
      type: object
      description: A football league or competition.
      properties:
        id:
          type: integer
          description: Unique identifier for the league.
        name:
          type: string
          description: Name of the league.
        country:
          type: string
          description: Country the league is associated with.
        logoUrl:
          type: string
          format: uri
          description: URL to the league logo image.
        currentSeasonId:
          type: integer
          description: ID of the currently active season.
    Season:
      type: object
      description: A league season.
      properties:
        id:
          type: integer
          description: Unique identifier for the season.
        leagueId:
          type: integer
          description: ID of the parent league.
        name:
          type: string
          description: Season name (e.g., 2025/2026).
        startDate:
          type: string
          format: date
          description: Season start date.
        endDate:
          type: string
          format: date
          description: Season end date.
        isCurrent:
          type: boolean
          description: Whether this is the current active season.
    Match:
      type: object
      description: A football match with score and basic information.
      properties:
        id:
          type: integer
          description: Unique identifier for the match.
        homeTeam:
          $ref: '#/components/schemas/TeamRef'
        awayTeam:
          $ref: '#/components/schemas/TeamRef'
        homeScore:
          type: integer
          description: Home team score.
        awayScore:
          type: integer
          description: Away team score.
        status:
          type: string
          enum:
            - live
            - scheduled
            - finished
          description: Current match status.
        matchDate:
          type: string
          format: date-time
          description: Date and time of the match.
        leagueId:
          type: integer
          description: ID of the league this match belongs to.
        seasonId:
          type: integer
          description: ID of the season this match belongs to.
        minute:
          type: integer
          description: Current match minute (for live matches).
    MatchDetail:
      allOf:
        - $ref: '#/components/schemas/Match'
        - type: object
          properties:
            homeLineup:
              type: array
              items:
                $ref: '#/components/schemas/LineupPlayer'
              description: Home team lineup.
            awayLineup:
              type: array
              items:
                $ref: '#/components/schemas/LineupPlayer'
              description: Away team lineup.
            events:
              type: array
              items:
                $ref: '#/components/schemas/MatchEvent'
              description: Match events (goals, cards, substitutions).
            statistics:
              $ref: '#/components/schemas/MatchStatistics'
            headToHead:
              type: array
              items:
                $ref: '#/components/schemas/Match'
              description: Previous matches between the two teams.
    TeamRef:
      type: object
      description: A lightweight team reference.
      properties:
        id:
          type: integer
          description: Team identifier.
        name:
          type: string
          description: Team name.
        nameTranslated:
          type: string
          description: Translated team name if available.
    Team:
      type: object
      description: A football team with full details.
      properties:
        id:
          type: integer
          description: Unique identifier for the team.
        name:
          type: string
          description: Team name.
        nameTranslated:
          type: string
          description: Translated team name.
        country:
          type: string
          description: Country of the team.
        logoUrl:
          type: string
          format: uri
          description: URL to the team logo.
        founded:
          type: integer
          description: Year the team was founded.
        stadium:
          type: string
          description: Name of the team's home stadium.
        players:
          type: array
          items:
            $ref: '#/components/schemas/PlayerRef'
          description: Current squad players.
    Player:
      type: object
      description: A football player with full details.
      properties:
        id:
          type: integer
          description: Unique identifier for the player.
        name:
          type: string
          description: Player name.
        nameTranslated:
          type: string
          description: Translated player name if available.
        nationality:
          type: string
          description: Player nationality.
        position:
          type: string
          description: Player position (e.g., Forward, Midfielder).
        dateOfBirth:
          type: string
          format: date
          description: Player date of birth.
        teamId:
          type: integer
          description: Current team ID.
        shirtNumber:
          type: integer
          description: Player shirt number.
    PlayerRef:
      type: object
      description: A lightweight player reference.
      properties:
        id:
          type: integer
          description: Player identifier.
        name:
          type: string
          description: Player name.
        position:
          type: string
          description: Player position.
    LineupPlayer:
      type: object
      description: A player in a match lineup.
      properties:
        playerId:
          type: integer
          description: Player identifier.
        name:
          type: string
          description: Player name.
        position:
          type: string
          description: Player position.
        shirtNumber:
          type: integer
          description: Shirt number worn in this match.
        isStarting:
          type: boolean
          description: Whether the player is in the starting eleven.
    MatchEvent:
      type: object
      description: An event that occurred during a match.
      properties:
        minute:
          type: integer
          description: Minute of the match when the event occurred.
        type:
          type: string
          enum:
            - goal
            - yellow_card
            - red_card
            - substitution
            - penalty
          description: Type of match event.
        playerId:
          type: integer
          description: ID of the player involved in the event.
        teamId:
          type: integer
          description: ID of the team involved.
    MatchStatistics:
      type: object
      description: Match statistics for both teams.
      properties:
        homePossession:
          type: number
          description: Home team ball possession percentage.
        awayPossession:
          type: number
          description: Away team ball possession percentage.
        homeShots:
          type: integer
          description: Total shots by home team.
        awayShots:
          type: integer
          description: Total shots by away team.
        homeShotsOnTarget:
          type: integer
          description: Shots on target by home team.
        awayShotsOnTarget:
          type: integer
          description: Shots on target by away team.
        homeCorners:
          type: integer
          description: Corners by home team.
        awayCorners:
          type: integer
          description: Corners by away team.
    StandingEntry:
      type: object
      description: A team's position in the league standings.
      properties:
        position:
          type: integer
          description: Current position in the table.
        team:
          $ref: '#/components/schemas/TeamRef'
        played:
          type: integer
          description: Matches played.
        won:
          type: integer
          description: Matches won.
        drawn:
          type: integer
          description: Matches drawn.
        lost:
          type: integer
          description: Matches lost.
        goalsFor:
          type: integer
          description: Goals scored.
        goalsAgainst:
          type: integer
          description: Goals conceded.
        goalDifference:
          type: integer
          description: Goal difference (goalsFor - goalsAgainst).
        points:
          type: integer
          description: Total points.
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message describing the authentication failure.
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message indicating the resource was not found.