Odds-API.io Events API

openapi: 3.2.0
info:
  description: 'Odds-API.io is a powerful sports betting odds comparison API, providing real-time data from 450+ bookmakers across 34 sports with near zero latency.


    - 450+ bookmakers supported

    - 34 sports including Football, Basketball, Tennis, Esports and more

    - Real-time odds with close to zero latency

    - Pre-match & In-play odds coverage

    - 99.9% uptime for reliability'
  title: Odds-API.io - Real-Time Sports Betting Odds API (v3) Events…
  contact: {}
  version: 3.0.0
servers:
- url: https://api.odds-api.io/v3
tags:
- name: Events
paths:
  /events:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns events with enhanced filtering and pagination
      tags:
      - Events
      summary: Get Events
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: '"football"'
        description: Sport name or slug (e.g. Football or football)
        name: sport
        in: query
        required: true
        schema:
          type: string
      - example: '"england-premier-league"'
        description: League slug (e.g. england-premier-league)
        name: league
        in: query
        schema:
          type: string
      - example: 38
        description: Filter by participant ID (home or away)
        name: participantId
        in: query
        schema:
          type: integer
      - example: '"pending,live"'
        description: Comma-separated event statuses (e.g. pending,live,settled,cancelled)
        name: status
        in: query
        schema:
          type: string
      - example: '"2025-10-28T10:00:00Z"'
        description: Start date/time in RFC3339 format (e.g. 2025-10-28T10:00:00Z)
        name: from
        in: query
        schema:
          type: string
      - example: '"2025-10-28T23:59:59Z"'
        description: End date/time in RFC3339 format (e.g. 2025-10-28T23:59:59Z). If omitted, defaults to 14 days from now.
        name: to
        in: query
        schema:
          type: string
      - example: '"SingBet"'
        description: Filter by bookmaker name - returns only events that have odds available from this bookmaker (e.g. SingBet)
        name: bookmaker
        in: query
        schema:
          type: string
      - example: 20
        description: Maximum number of events to return. Every response is capped at 5000; use limit + skip to paginate larger ranges.
        name: limit
        in: query
        schema:
          type: integer
      - example: 0
        description: Number of events to skip (for pagination)
        name: skip
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/dto.SimpleEventDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: List events for a sport, filtered by league, participant, status, dates or bookmaker. Returns teams, kickoff, status and scores, paged with limit and skip.
      operationId: getEvents
      x-operation-id-source: derived
  /events/live:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns all currently live events from all sports with optional sport filter
      tags:
      - Events
      summary: Get Live Events
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: '"football"'
        description: Sport name or slug to filter by (e.g. Football or football)
        name: sport
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/dto.SimpleEventDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Get every event in play right now across all sports, or filter by one sport. Each event includes teams, league, live scores, match clock and status.
      operationId: getEventsLive
      x-operation-id-source: derived
  /events/search:
    get:
      security:
      - ApiKeyAuth: []
      description: Searches events by team or league name and returns up to 10 results ranked by relevance. By default only upcoming (not yet started, not cancelled) events are searched. Pass status=live to search in-play events instead; live results include current scores and, where available, the match clock.
      tags:
      - Events
      summary: Search Events
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: '"Liverpool"'
        description: Search term (min 3 characters)
        name: query
        in: query
        required: true
        schema:
          type: string
      - description: 'Which events to search: upcoming (default) or live'
        name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - upcoming
          - live
          default: upcoming
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/dto.SimpleEventDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Search events by team or league name and get up to 10 matches ranked by relevance. Upcoming by default; pass status=live for in-play events with scores.
      operationId: getEventsSearch
      x-operation-id-source: derived
  /events/{id}:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns a single event by its unique identifier
      tags:
      - Events
      summary: Get Event by ID
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: 123456
        description: Event ID
        name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.SimpleEventDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: 'Get one event by id: home and away teams, league, sport, kickoff date, status, live scores and match clock, plus how many bookmakers are pricing it.'
      operationId: getEventsById
      x-operation-id-source: derived
components:
  schemas:
    dto.SideFloats:
      type: object
      description: 'Home/away pair that can be fractional. Cricket overs use cricket notation: 19.3 means nineteen overs and three balls.'
      properties:
        away:
          type: number
          example: 20
        home:
          type: number
          example: 20
    dto.PeriodScore:
      type: object
      properties:
        away:
          type: integer
        home:
          type: integer
        overs:
          allOf:
          - $ref: '#/components/schemas/dto.SideFloats'
          description: Cricket only. Overs bowled by each side in this innings.
        wickets:
          allOf:
          - $ref: '#/components/schemas/dto.SideInts'
          description: Cricket only. Wickets lost by each side in this innings.
    dto.EsportsDto:
      type: object
      description: Present on esports events only
      properties:
        game:
          allOf:
          - $ref: '#/components/schemas/dto.Sport'
          description: 'The game being played, e.g. {"name": "Valorant", "slug": "valorant"}'
        league:
          allOf:
          - $ref: '#/components/schemas/dto.League'
          description: Parent league (VCT, LCK, LEC). Its slug stays the same across the league's splits and stages.
        region:
          description: 'Region of the tournament: Western Europe, Eastern Europe, North America, South America, Asia, Oceania or Middle East. Omitted when unknown.'
          type: string
          example: Western Europe
        format:
          allOf:
          - $ref: '#/components/schemas/dto.EsportsFormatDto'
          description: Match format. Omitted when unknown.
    dto.EsportsFormatDto:
      type: object
      properties:
        type:
          description: bestOf or firstTo
          type: string
          example: bestOf
        games:
          description: 'Number of games: 3 for a best of 3'
          type: integer
          example: 3
    dto.Score:
      type: object
      properties:
        away:
          type: integer
        home:
          description: 'Headline result: includes overtime, never a penalty shootout.'
          type: integer
        periods:
          description: Keyed p1..pN (that period only), ft, ot and ap (running totals after regulation, overtime and a penalty shootout), currentgame, mapN, inningN. See https://docs.odds-api.io/guides/live-events#period-scores
          type: object
          additionalProperties:
            $ref: '#/components/schemas/dto.PeriodScore'
    dto.Sport:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
    dto.SideInts:
      type: object
      description: Home/away pair of whole numbers (cricket wickets).
      properties:
        away:
          type: integer
          example: 9
        home:
          type: integer
          example: 6
    controllers.ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Error message
    dto.SimpleEventDto:
      type: object
      properties:
        away:
          type: string
        awayId:
          type: integer
        bookmakerCount:
          type: integer
        date:
          type: string
        home:
          type: string
        homeId:
          type: integer
        id:
          type: integer
        league:
          $ref: '#/components/schemas/dto.League'
        scores:
          $ref: '#/components/schemas/dto.Score'
        sport:
          $ref: '#/components/schemas/dto.Sport'
        status:
          type: string
        clock:
          allOf:
          - $ref: '#/components/schemas/dto.ClockDto'
          description: Live match clock (live events only; absent when no clock data is available)
        esports:
          allOf:
          - $ref: '#/components/schemas/dto.EsportsDto'
          description: 'Esports events only: game, parent league, region and match format'
    dto.League:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
    dto.ClockDto:
      type: object
      description: Live match-clock state for in-play events. minute/playedSeconds are extrapolated server-side from the live feed and only advance while running is true.
      properties:
        minute:
          type: integer
          example: 67
          description: Current match minute
        playedSeconds:
          type: integer
          example: 4023
          description: Seconds of play elapsed
        period:
          type: integer
          example: 2
          description: Current period number
        running:
          type: boolean
          example: true
          description: Whether the clock is currently running
        statusDetail:
          type: string
          example: 2nd half
          description: Human-readable phase of play
        serve:
          type: string
          enum:
          - home
          - away
          description: Current server (tennis, table tennis, volleyball)
        injuryTime:
          type: integer
          example: 4
          description: Announced injury/stoppage time in minutes (football)
        periodStartedAt:
          type: integer
          example: 1792170000
          description: 'Unix timestamp (seconds) when the current period started. Sent only when the feed has no played clock (for example ice hockey games with basic coverage), never alongside playedSeconds. Wall time, not game time: a stopped clock makes the elapsed wall time longer than the time played, so never treat it as playedSeconds. Omitted when the value is missing, in the future, or more than 3 hours old. Also present in WebSocket clock snapshots.'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey
      description: Your Odds-API.io API key, sent as the apiKey query parameter. Get one at https://odds-api.io/pricing.
x-origin:
- url: https://api.odds-api.io/v3/docs/doc.json
  format: swagger
  version: '2.0'
  converter:
    url: https://github.com/mermade/oas-kit
    version: 7.0.8