openapi: 3.0.3
info:
  title: Sportmonks Football API
  description: |
    REST API providing soccer/football data including livescores, fixtures, schedules,
    standings, teams, players, predictions, and odds across 2,500+ leagues worldwide.

    All endpoints accept the API token either as an `Authorization` header or as an
    `api_token` query parameter. Responses are JSON and support `include`, `filters`,
    and `select` query parameters for response shaping.
  version: '3.0'
  contact:
    name: Sportmonks Support
    email: support@sportmonks.com
    url: https://www.sportmonks.com/
  termsOfService: https://www.sportmonks.com/terms-of-service/
  license:
    name: Sportmonks Commercial License
    url: https://www.sportmonks.com/terms-of-service/
servers:
  - url: https://api.sportmonks.com/v3/football
    description: Sportmonks Football API v3 production base URL
security:
  - ApiTokenHeader: []
  - ApiTokenQuery: []
tags:
  - name: Livescores
    description: Real-time score and match-state feeds.
  - name: Fixtures
    description: Scheduled and historical match fixtures.
  - name: Leagues
    description: Competition metadata across countries and seasons.
  - name: Seasons
    description: Season records and per-season fixture lists.
  - name: Standings
    description: League tables and group standings.
  - name: Teams
    description: Team profiles, squads, and metadata.
  - name: Players
    description: Player profiles, attributes, and career data.
  - name: Predictions
    description: Probabilities and predicted outcomes for upcoming fixtures.
  - name: Odds
    description: Pre-match and in-play betting odds.
  - name: Schedules
    description: Round and stage schedules per season.
paths:
  /livescores:
    get:
      operationId: listLivescores
      summary: List Livescores
      description: Returns all currently in-play and recently played fixtures.
      tags:
        - Livescores
      parameters:
        - $ref: '#/components/parameters/Include'
        - $ref: '#/components/parameters/Filters'
        - $ref: '#/components/parameters/Select'
      responses:
        '200':
          description: A list of livescores.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixtureCollection'
  /livescores/inplay:
    get:
      operationId: listInplayLivescores
      summary: List In-Play Livescores
      description: Returns only fixtures currently in progress.
      tags:
        - Livescores
      parameters:
        - $ref: '#/components/parameters/Include'
        - $ref: '#/components/parameters/Filters'
      responses:
        '200':
          description: A list of in-play fixtures.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixtureCollection'
  /fixtures:
    get:
      operationId: listFixtures
      summary: List Fixtures
      description: Returns paginated fixtures across leagues and seasons.
      tags:
        - Fixtures
      parameters:
        - $ref: '#/components/parameters/Include'
        - $ref: '#/components/parameters/Filters'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of fixtures.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixtureCollection'
  /fixtures/{id}:
    get:
      operationId: getFixture
      summary: Get Fixture By ID
      description: Returns a single fixture by its identifier.
      tags:
        - Fixtures
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: A single fixture.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixtureEnvelope'
  /fixtures/date/{date}:
    get:
      operationId: listFixturesByDate
      summary: List Fixtures By Date
      description: Returns fixtures scheduled on a specific calendar date (YYYY-MM-DD).
      tags:
        - Fixtures
      parameters:
        - name: date
          in: path
          required: true
          schema:
            type: string
            format: date
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: Fixtures on the given date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FixtureCollection'
  /leagues:
    get:
      operationId: listLeagues
      summary: List Leagues
      description: Returns all leagues accessible to the authenticated subscription.
      tags:
        - Leagues
      parameters:
        - $ref: '#/components/parameters/Include'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A list of leagues.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeagueCollection'
  /leagues/{id}:
    get:
      operationId: getLeague
      summary: Get League By ID
      description: Returns a single league by identifier.
      tags:
        - Leagues
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: A single league.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeagueEnvelope'
  /seasons:
    get:
      operationId: listSeasons
      summary: List Seasons
      description: Returns all season records.
      tags:
        - Seasons
      responses:
        '200':
          description: A list of seasons.
  /standings/seasons/{seasonId}:
    get:
      operationId: getStandingsBySeason
      summary: Get Standings By Season
      description: Returns the league table for a given season.
      tags:
        - Standings
      parameters:
        - name: seasonId
          in: path
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: Standings for the season.
  /teams:
    get:
      operationId: listTeams
      summary: List Teams
      description: Returns paginated teams across covered leagues.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/Include'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A list of teams.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamCollection'
  /teams/{id}:
    get:
      operationId: getTeam
      summary: Get Team By ID
      description: Returns a single team by identifier.
      tags:
        - Teams
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: A single team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamEnvelope'
  /players:
    get:
      operationId: listPlayers
      summary: List Players
      description: Returns paginated players across covered leagues.
      tags:
        - Players
      parameters:
        - $ref: '#/components/parameters/Include'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A list of players.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerCollection'
  /players/{id}:
    get:
      operationId: getPlayer
      summary: Get Player By ID
      description: Returns a single player profile.
      tags:
        - Players
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: A single player.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerEnvelope'
  /predictions/probabilities/fixtures/{fixtureId}:
    get:
      operationId: getPredictionByFixture
      summary: Get Prediction Probabilities For Fixture
      description: Returns outcome probabilities for a fixture.
      tags:
        - Predictions
      parameters:
        - name: fixtureId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Prediction probabilities for the fixture.
  /odds/pre-match/fixtures/{fixtureId}:
    get:
      operationId: getPreMatchOddsByFixture
      summary: Get Pre-Match Odds For Fixture
      description: Returns pre-match bookmaker odds for a fixture.
      tags:
        - Odds
      parameters:
        - name: fixtureId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Pre-match odds.
  /odds/inplay/fixtures/{fixtureId}:
    get:
      operationId: getInplayOddsByFixture
      summary: Get In-Play Odds For Fixture
      description: Returns live in-play bookmaker odds for a fixture.
      tags:
        - Odds
      parameters:
        - name: fixtureId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: In-play odds.
  /schedules/seasons/{seasonId}:
    get:
      operationId: getScheduleBySeason
      summary: Get Schedule By Season
      description: Returns the round-by-round schedule for a season.
      tags:
        - Schedules
      parameters:
        - name: seasonId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Season schedule.
components:
  securitySchemes:
    ApiTokenHeader:
      type: apiKey
      in: header
      name: Authorization
      description: Sportmonks API token passed as the value of the Authorization header.
    ApiTokenQuery:
      type: apiKey
      in: query
      name: api_token
      description: Sportmonks API token passed as the api_token query parameter.
  parameters:
    Include:
      name: include
      in: query
      description: Semicolon-separated list of related entities to embed in the response.
      required: false
      schema:
        type: string
    Filters:
      name: filters
      in: query
      description: Semicolon-separated filter expressions applied to the collection.
      required: false
      schema:
        type: string
    Select:
      name: select
      in: query
      description: Comma-separated list of fields to include in each entity (field selection).
      required: false
      schema:
        type: string
    Page:
      name: page
      in: query
      description: Page number for paginated collection responses.
      required: false
      schema:
        type: integer
        minimum: 1
  schemas:
    Pagination:
      type: object
      properties:
        count:
          type: integer
        per_page:
          type: integer
        current_page:
          type: integer
        next_page:
          type: string
          nullable: true
        has_more:
          type: boolean
    Subscription:
      type: object
      properties:
        meta:
          type: object
        plans:
          type: array
          items:
            type: object
        add_ons:
          type: array
          items:
            type: object
        widgets:
          type: array
          items:
            type: object
    RateLimit:
      type: object
      properties:
        resets_in_seconds:
          type: integer
        remaining:
          type: integer
        requested_entity:
          type: string
    Fixture:
      type: object
      properties:
        id:
          type: integer
        sport_id:
          type: integer
        league_id:
          type: integer
        season_id:
          type: integer
        stage_id:
          type: integer
          nullable: true
        round_id:
          type: integer
          nullable: true
        state_id:
          type: integer
        venue_id:
          type: integer
          nullable: true
        name:
          type: string
        starting_at:
          type: string
          format: date-time
        result_info:
          type: string
          nullable: true
        leg:
          type: string
          nullable: true
        details:
          type: string
          nullable: true
        length:
          type: integer
          nullable: true
        placeholder:
          type: boolean
        has_odds:
          type: boolean
        has_premium_odds:
          type: boolean
        starting_at_timestamp:
          type: integer
    FixtureEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Fixture'
        subscription:
          $ref: '#/components/schemas/Subscription'
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
    FixtureCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Fixture'
        pagination:
          $ref: '#/components/schemas/Pagination'
        subscription:
          $ref: '#/components/schemas/Subscription'
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
    League:
      type: object
      properties:
        id:
          type: integer
        sport_id:
          type: integer
        country_id:
          type: integer
        name:
          type: string
        active:
          type: boolean
        short_code:
          type: string
          nullable: true
        image_path:
          type: string
        type:
          type: string
        sub_type:
          type: string
          nullable: true
        last_played_at:
          type: string
          format: date-time
          nullable: true
        category:
          type: integer
          nullable: true
        has_jerseys:
          type: boolean
    LeagueEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/League'
    LeagueCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/League'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Team:
      type: object
      properties:
        id:
          type: integer
        sport_id:
          type: integer
        country_id:
          type: integer
        venue_id:
          type: integer
          nullable: true
        gender:
          type: string
        name:
          type: string
        short_code:
          type: string
          nullable: true
        image_path:
          type: string
        founded:
          type: integer
          nullable: true
        type:
          type: string
        placeholder:
          type: boolean
        last_played_at:
          type: string
          format: date-time
          nullable: true
    TeamEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Team'
    TeamCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Team'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Player:
      type: object
      properties:
        id:
          type: integer
        sport_id:
          type: integer
        country_id:
          type: integer
          nullable: true
        nationality_id:
          type: integer
          nullable: true
        city_id:
          type: integer
          nullable: true
        position_id:
          type: integer
          nullable: true
        detailed_position_id:
          type: integer
          nullable: true
        type_id:
          type: integer
          nullable: true
        common_name:
          type: string
        firstname:
          type: string
        lastname:
          type: string
        name:
          type: string
        display_name:
          type: string
        image_path:
          type: string
        height:
          type: integer
          nullable: true
        weight:
          type: integer
          nullable: true
        date_of_birth:
          type: string
          format: date
          nullable: true
        gender:
          type: string
    PlayerEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Player'
    PlayerCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Player'
        pagination:
          $ref: '#/components/schemas/Pagination'