openapi: 3.0.3
info:
  title: Kickoffapi — Football Data API
  version: "1.0.0"
  description: >-
    Real-time football (soccer) data API: live scores, fixtures, results, deep player
    and team statistics, lineups, head-to-head, standings, transfers, in-play odds and
    900+ leagues, delivered as predictable JSON with rate-limit headers on every response.
    Authenticate by sending your key in the x-api-key header.
  contact:
    name: Kickoffapi Support
    email: contact@kickoffapi.com
    url: https://kickoffapi.com
servers:
  - url: https://api.kickoffapi.com/api/v1
    description: Production
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    Envelope:
      type: object
      properties:
        get:
          type: string
          description: The endpoint that was queried.
        results:
          type: integer
          description: Number of items returned in response.
        response:
          type: array
          description: The result payload.
          items:
            type: object
  responses:
    Success:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
    Unauthorized:
      description: Missing or invalid x-api-key header.
    RateLimited:
      description: Rate limit or quota exceeded.
paths:
  /coachs:
    get:
      summary: Coachs
      operationId: getCoachs
      tags: [football]
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /countries:
    get:
      summary: Countries
      operationId: getCountries
      tags: [football]
      parameters:
        - name: name
          in: query
          required: false
          schema:
            type: string
        - name: code
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /fixtures:
    get:
      summary: Fixtures
      operationId: getFixtures
      tags: [football]
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: ids
          in: query
          required: false
          schema:
            type: string
        - name: live
          in: query
          required: false
          schema:
            type: string
        - name: date
          in: query
          required: false
          schema:
            type: string
        - name: league
          in: query
          required: false
          schema:
            type: string
        - name: season
          in: query
          required: false
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
        - name: last
          in: query
          required: false
          schema:
            type: string
        - name: next
          in: query
          required: false
          schema:
            type: string
        - name: from
          in: query
          required: false
          schema:
            type: string
        - name: to
          in: query
          required: false
          schema:
            type: string
        - name: round
          in: query
          required: false
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            type: string
        - name: venue
          in: query
          required: false
          schema:
            type: string
        - name: timezone
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /fixtures/events:
    get:
      summary: Events
      operationId: getFixturesEvents
      tags: [football]
      parameters:
        - name: fixture
          in: query
          required: true
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
        - name: player
          in: query
          required: false
          schema:
            type: string
        - name: type
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /fixtures/headtohead:
    get:
      summary: Head To Head
      operationId: getFixturesHeadtohead
      tags: [football]
      parameters:
        - name: h2h
          in: query
          required: true
          schema:
            type: string
        - name: date
          in: query
          required: false
          schema:
            type: string
        - name: league
          in: query
          required: false
          schema:
            type: string
        - name: season
          in: query
          required: false
          schema:
            type: string
        - name: last
          in: query
          required: false
          schema:
            type: string
        - name: next
          in: query
          required: false
          schema:
            type: string
        - name: from
          in: query
          required: false
          schema:
            type: string
        - name: to
          in: query
          required: false
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            type: string
        - name: venue
          in: query
          required: false
          schema:
            type: string
        - name: timezone
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /fixtures/lineups:
    get:
      summary: Lineups
      operationId: getFixturesLineups
      tags: [football]
      parameters:
        - name: fixture
          in: query
          required: true
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
        - name: player
          in: query
          required: false
          schema:
            type: string
        - name: type
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /fixtures/players:
    get:
      summary: Players statistics
      operationId: getFixturesPlayers
      tags: [football]
      parameters:
        - name: fixture
          in: query
          required: true
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /fixtures/rounds:
    get:
      summary: Rounds
      operationId: getFixturesRounds
      tags: [football]
      parameters:
        - name: league
          in: query
          required: true
          schema:
            type: string
        - name: season
          in: query
          required: true
          schema:
            type: string
        - name: current
          in: query
          required: false
          schema:
            type: string
        - name: dates
          in: query
          required: false
          schema:
            type: string
        - name: timezone
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /fixtures/statistics:
    get:
      summary: Statistics
      operationId: getFixturesStatistics
      tags: [football]
      parameters:
        - name: fixture
          in: query
          required: true
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
        - name: type
          in: query
          required: false
          schema:
            type: string
        - name: half
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /injuries:
    get:
      summary: Injuries
      operationId: getInjuries
      tags: [football]
      parameters:
        - name: league
          in: query
          required: false
          schema:
            type: string
        - name: season
          in: query
          required: false
          schema:
            type: string
        - name: fixture
          in: query
          required: false
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
        - name: player
          in: query
          required: false
          schema:
            type: string
        - name: date
          in: query
          required: false
          schema:
            type: string
        - name: ids
          in: query
          required: false
          schema:
            type: string
        - name: timezone
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /leagues:
    get:
      summary: Leagues
      operationId: getLeagues
      tags: [football]
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: name
          in: query
          required: false
          schema:
            type: string
        - name: country
          in: query
          required: false
          schema:
            type: string
        - name: code
          in: query
          required: false
          schema:
            type: string
        - name: season
          in: query
          required: false
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
        - name: type
          in: query
          required: false
          schema:
            type: string
        - name: current
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
        - name: last
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /leagues/seasons:
    get:
      summary: Seasons
      operationId: getLeaguesSeasons
      tags: [football]
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /odds:
    get:
      summary: Odds
      operationId: getOdds
      tags: [football]
      parameters:
        - name: fixture
          in: query
          required: false
          schema:
            type: string
        - name: league
          in: query
          required: false
          schema:
            type: string
        - name: season
          in: query
          required: false
          schema:
            type: string
        - name: date
          in: query
          required: false
          schema:
            type: string
        - name: timezone
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: string
        - name: bookmaker
          in: query
          required: false
          schema:
            type: string
        - name: bet
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /odds/bets:
    get:
      summary: Bets
      operationId: getOddsBets
      tags: [football]
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /odds/bookmakers:
    get:
      summary: Bookmakers
      operationId: getOddsBookmakers
      tags: [football]
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /odds/live:
    get:
      summary: odds/live
      operationId: getOddsLive
      tags: [football]
      parameters:
        - name: fixture
          in: query
          required: false
          schema:
            type: string
        - name: league
          in: query
          required: false
          schema:
            type: string
        - name: bet
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /odds/live/bets:
    get:
      summary: odds/live/bets
      operationId: getOddsLiveBets
      tags: [football]
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /odds/mapping:
    get:
      summary: Mapping
      operationId: getOddsMapping
      tags: [football]
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players:
    get:
      summary: Statistics
      operationId: getPlayers
      tags: [football]
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
        - name: league
          in: query
          required: false
          schema:
            type: string
        - name: season
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players/profiles:
    get:
      summary: Profiles
      operationId: getPlayersProfiles
      tags: [football]
      parameters:
        - name: player
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players/seasons:
    get:
      summary: Seasons
      operationId: getPlayersSeasons
      tags: [football]
      parameters:
        - name: player
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players/squads:
    get:
      summary: Squads
      operationId: getPlayersSquads
      tags: [football]
      parameters:
        - name: team
          in: query
          required: false
          schema:
            type: string
        - name: player
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players/teams:
    get:
      summary: Teams
      operationId: getPlayersTeams
      tags: [football]
      parameters:
        - name: player
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players/topassists:
    get:
      summary: Top Assists
      operationId: getPlayersTopassists
      tags: [football]
      parameters:
        - name: league
          in: query
          required: true
          schema:
            type: string
        - name: season
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players/topredcards:
    get:
      summary: Top Red Cards
      operationId: getPlayersTopredcards
      tags: [football]
      parameters:
        - name: league
          in: query
          required: true
          schema:
            type: string
        - name: season
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players/topscorers:
    get:
      summary: Top Scorers
      operationId: getPlayersTopscorers
      tags: [football]
      parameters:
        - name: league
          in: query
          required: true
          schema:
            type: string
        - name: season
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players/topyellowcards:
    get:
      summary: Top Yellow Cards
      operationId: getPlayersTopyellowcards
      tags: [football]
      parameters:
        - name: league
          in: query
          required: true
          schema:
            type: string
        - name: season
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /predictions:
    get:
      summary: Predictions
      operationId: getPredictions
      tags: [football]
      parameters:
        - name: fixture
          in: query
          required: true
          schema:
            type: string
        - name: fixtureId
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /sidelined:
    get:
      summary: Sidelined
      operationId: getSidelined
      tags: [football]
      parameters:
        - name: player
          in: query
          required: false
          schema:
            type: string
        - name: players
          in: query
          required: false
          schema:
            type: string
        - name: coach
          in: query
          required: false
          schema:
            type: string
        - name: coachs
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /standings:
    get:
      summary: Standings
      operationId: getStandings
      tags: [football]
      parameters:
        - name: league
          in: query
          required: false
          schema:
            type: string
        - name: season
          in: query
          required: true
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /teams:
    get:
      summary: Teams information
      operationId: getTeams
      tags: [football]
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: name
          in: query
          required: false
          schema:
            type: string
        - name: league
          in: query
          required: false
          schema:
            type: string
        - name: season
          in: query
          required: false
          schema:
            type: string
        - name: country
          in: query
          required: false
          schema:
            type: string
        - name: code
          in: query
          required: false
          schema:
            type: string
        - name: venue
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /teams/countries:
    get:
      summary: Teams countries
      operationId: getTeamsCountries
      tags: [football]
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /teams/seasons:
    get:
      summary: Teams seasons
      operationId: getTeamsSeasons
      tags: [football]
      parameters:
        - name: team
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /teams/statistics:
    get:
      summary: Teams statistics
      operationId: getTeamsStatistics
      tags: [football]
      parameters:
        - name: league
          in: query
          required: true
          schema:
            type: string
        - name: season
          in: query
          required: true
          schema:
            type: string
        - name: team
          in: query
          required: true
          schema:
            type: string
        - name: date
          in: query
          required: false
          schema:
            type: string
        - name: teamId
          in: query
          required: false
          schema:
            type: string
        - name: leagueId
          in: query
          required: false
          schema:
            type: string
        - name: year
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /timezone:
    get:
      summary: Timezone
      operationId: getTimezone
      tags: [football]
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /transfers:
    get:
      summary: Transfers
      operationId: getTransfers
      tags: [football]
      parameters:
        - name: player
          in: query
          required: false
          schema:
            type: string
        - name: team
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /trophies:
    get:
      summary: Trophies
      operationId: getTrophies
      tags: [football]
      parameters:
        - name: player
          in: query
          required: false
          schema:
            type: string
        - name: players
          in: query
          required: false
          schema:
            type: string
        - name: coach
          in: query
          required: false
          schema:
            type: string
        - name: coachs
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /venues:
    get:
      summary: Venues
      operationId: getVenues
      tags: [football]
      parameters:
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: name
          in: query
          required: false
          schema:
            type: string
        - name: city
          in: query
          required: false
          schema:
            type: string
        - name: country
          in: query
          required: false
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'