Odds-API.io Odds 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: API.io - Real-Time Sports Betting API (v3) Odds API
  contact: {}
  version: 3.0.0
servers:
- url: https://api.odds-api.io/v3
tags:
- name: Odds
paths:
  /odds:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns odds comparison for a specific event from selected bookmakers.
      tags:
      - Odds
      summary: Get Event Odds
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: '"123456"'
        description: Event ID
        name: eventId
        in: query
        required: true
        schema:
          type: string
      - example: '"Bet365,Unibet"'
        description: Comma-separated list of bookmaker names (max 30)
        name: bookmakers
        in: query
        required: true
        schema:
          type: string
      - description: Comma-separated market names to keep, case-insensitive (max 40)
        name: markets
        in: query
        schema:
          type: string
        example: ML,Spread,Totals
      - example: true
        description: Set to true to get the current WebSocket sequence number in the `X-OddsAPI-Seq` response header. Pass it as `lastSeq` when you open or reopen the WebSocket, so updates after this snapshot are replayed.
        name: includeSeq
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          headers:
            X-OddsAPI-Seq:
              description: Current WebSocket sequence number. Sent when `includeSeq=true`.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.EventResponse'
        '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 odds for one event from your chosen bookmakers in one response, with every market each bookmaker offers, its prices and a link to the event page.
      operationId: getOdds
      x-operation-id-source: derived
  /odds/movements:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Returns the prematch odds movements for one market line of an event from a bookmaker: the opening price, the latest price and recent price changes (how many are kept depends on the bookmaker feed). Market and bookmaker names are case-insensitive. A 404 explains what is missing and lists the markets or lines that do have history. History is recorded only for a fixed set of bookmakers: 10BET, 12bet, 18bet, 1xbet, 22Bet, 888Sport, BC.Game, Bet365, Betano, Betclic FR, Betfair Exchange, Betfair Sportsbook, Betinia DK, BetMGM, BetOnline.ag, Betsson, BetVictor, Betway, Bovada, Bwin ES, Bwin IT, Circa, CloudBet, ComeOn, Coolbet, DanskeSpil, DraftKings, Duel, Eurobet IT, FanDuel, FB Sports, GG.bet, Goldbet IT, HKJC, Interwetten, Kalshi, Kambi, Ladbrokes, M88, Marathonbet, NetBet, NordicBet, Norsk Tipping, Novibet, Novibet GR, ON Sharp, Paddy Power, Pamestoixima, Polymarket, Rollbit, Roobet, Sbobet, Sharp Exchange, SingBet, Sisal IT, Snai IT, SportyBet, Stake, Stoiximan, Superbet, Tipico DE, Tipsport.cz, Unibet, Unibet FR, Vbet, Veikkaus, William Hill, Winamax FR, and selected sharp books. Requesting a bookmaker outside this set returns a 404.'
      tags:
      - Odds
      summary: Get Odds Movements
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: '"123456"'
        description: Event ID
        name: eventId
        in: query
        required: true
        schema:
          type: string
      - description: Bookmaker name, case-insensitive (e.g. Bet365, SingBet, Bet365 (no latency))
        name: bookmaker
        in: query
        required: true
        schema:
          type: string
      - description: Market name, case-insensitive (e.g. ML, Spread, Totals, Both Teams To Score)
        name: market
        in: query
        required: true
        schema:
          type: string
      - description: Handicap line (e.g. 0.5, -1.25, 2.5). Leave it out for the main line of Spread and Totals markets, where each entry's hdp shows the line at that time, or for markets without a line (ML, Draw No Bet, Both Teams To Score)
        name: marketLine
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.HandicapMovementsResponse'
        '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 prematch odds movements for one market line from one bookmaker: opening price, latest price and recent changes, for a fixed set of tracked bookmakers.'
      operationId: getOddsMovements
      x-operation-id-source: derived
  /odds/multi:
    get:
      description: Returns odds comparison for up to 10 events from selected bookmakers (counts as only 1 request).
      tags:
      - Odds
      summary: Get Odds for Multiple Events
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - description: Comma-separated list of up to 10 Event IDs
        name: eventIds
        in: query
        required: true
        schema:
          type: string
      - description: Comma-separated list of bookmaker names (max 30)
        name: bookmakers
        in: query
        required: true
        schema:
          type: string
      - description: Comma-separated market names to keep, case-insensitive (max 40)
        name: markets
        in: query
        schema:
          type: string
        example: ML,Spread,Totals
      - example: true
        description: Set to true to get the current WebSocket sequence number in the `X-OddsAPI-Seq` response header. Pass it as `lastSeq` when you open or reopen the WebSocket, so updates after this snapshot are replayed.
        name: includeSeq
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          headers:
            X-OddsAPI-Seq:
              description: Current WebSocket sequence number. Sent when `includeSeq=true`.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/controllers.EventResponse'
        '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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Get odds for up to 10 events from your chosen bookmakers in one call, counted as a single request, with the same markets as the single-event odds endpoint.
      security:
      - ApiKeyAuth: []
      operationId: getOddsMulti
      x-operation-id-source: derived
  /odds/updated:
    get:
      description: 'Returns updated event odds for a specific bookmaker since a given UNIX timestamp (max 90 seconds old). The response is a delta: each event carries only the market groups whose `updatedAt` is at or after `since`, and an event with no changed market group is omitted entirely. Merge responses by event and market name; a market that is absent has not changed, and a withdrawn market is not signalled here (re-read the event with `/odds`, or use the WebSocket feed).'
      tags:
      - Odds
      summary: Get updated event odds since a given timestamp
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - description: Unix timestamp (max 90 seconds old)
        name: since
        in: query
        required: true
        schema:
          type: integer
      - description: Bookmaker name (e.g. Bet365). The response uses the same name; `bookmaker=Bet365` also returns a `Bet365 (no latency)` key, as `/odds/multi` does.
        name: bookmaker
        in: query
        required: true
        schema:
          type: string
      - description: Sport name (e.g. Football)
        name: sport
        in: query
        required: true
        schema:
          type: string
      - description: Max events to return (default and maximum 10000)
        name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 10000
      - description: 'Comma-separated market names to keep, case-insensitive (max 40). Required from 19 October 2026: a call without it, or where none of the names exist, returns 400. Valid names: /v3/markets?sport=<sport>'
        name: markets
        in: query
        schema:
          type: string
        example: ML,Spread,Totals
      responses:
        '200':
          description: OK
          headers:
            X-Server-Time:
              description: Unix seconds captured on the server just before the query ran
              schema:
                type: integer
            X-Next-Since:
              description: Value to pass as `since` on the next call. X-Server-Time minus 10 seconds when the response was not truncated by `limit`, so odds that become visible a few seconds after they were stamped are not skipped (the overlap can re-send recent updates; merge them by event and market); otherwise the unix-second floor of the last returned event's `updated_at`. Accepted as `since` while it is no more than 100 seconds old, so drain truncated pages promptly
              schema:
                type: integer
            X-Unknown-Markets:
              description: Requested market names that do not exist, when some but not all are unknown
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/controllers.EventResponse'
        '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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Get odds from one bookmaker for events updated since a UNIX timestamp up to 90 seconds old, so you can poll for changes instead of refetching every event.
      security:
      - ApiKeyAuth: []
      operationId: getOddsUpdated
      x-operation-id-source: derived
  /odds/summary:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Best, average, median, worst and margin-free fair price per market line across bookmakers, for odds comparison pages. A bookmaker counts only while its prices are updating (a change within 5 minutes before kickoff, 60 seconds live). Exchanges are reported separately. Available on Growth plans and above. Free, Solo and Starter plans receive a sample response with demo set to true and an X-OddsAPI-Demo: true header.'
      tags:
      - Odds
      summary: Get Odds Summary
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - description: Event ID
        name: eventId
        in: query
        required: true
        schema:
          type: string
        example: '"123456"'
      - description: Comma-separated market names, case-insensitive (default ML,Spread,Totals, max 20)
        name: markets
        in: query
        schema:
          type: string
      - description: main (default) returns each ladder market's main line; all returns every line priced by at least 3 bookmakers
        name: lines
        in: query
        schema:
          type: string
      - description: Restrict the summary to these bookmakers. Each must be in your selected bookmakers
        name: bookmakers
        in: query
        schema:
          type: string
      - description: Add the best exchange back price per outcome in a separate exchanges block
        name: includeExchanges
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.EventSummary'
        '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'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Best, average, median, worst and margin-free fair price per market line across bookmakers for one event, for odds comparison pages. Growth plans and up.
      operationId: getOddsSummary
      x-operation-id-source: derived
  /odds/summary/multi:
    get:
      security:
      - ApiKeyAuth: []
      description: 'The odds summary for up to 10 events in one request, counted as one request. Events that are not found are left out. Available on Growth plans and above. Free, Solo and Starter plans receive sample responses with demo set to true and an X-OddsAPI-Demo: true header.'
      tags:
      - Odds
      summary: Get Odds Summary for Multiple Events
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - description: Comma-separated event IDs, up to 10
        name: eventIds
        in: query
        required: true
        schema:
          type: string
      - description: Comma-separated market names, case-insensitive (default ML,Spread,Totals, max 20)
        name: markets
        in: query
        schema:
          type: string
      - description: main (default) or all
        name: lines
        in: query
        schema:
          type: string
      - description: Restrict the summary to these bookmakers. Each must be in your selected bookmakers
        name: bookmakers
        in: query
        schema:
          type: string
      - description: Add the best exchange back price per outcome in a separate exchanges block
        name: includeExchanges
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/controllers.EventSummary'
        '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'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: 'The odds summary for up to 10 events in one call, counted as one request: best, average, median, worst and fair price per line. Growth plans and above.'
      operationId: getOddsSummaryMulti
      x-operation-id-source: derived
components:
  schemas:
    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.
    controllers.SummaryOutcome:
      type: object
      properties:
        average:
          type: number
        best:
          type: number
        bestBookmakers:
          type: array
          items:
            type: string
        excluded:
          type: integer
        fair:
          type: number
        median:
          type: number
        sharpFair:
          type: number
        worst:
          type: number
    controllers.League:
      type: object
      properties:
        name:
          type: string
          example: Premier League
        slug:
          type: string
          example: premier-league
    controllers.SummaryExchanges:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/controllers.SummaryExchangeQuote'
    controllers.EventSummary:
      type: object
      properties:
        away:
          type: string
        computedAt:
          type: string
        date:
          type: string
        demo:
          type: boolean
        eventId:
          type: string
        home:
          type: string
        markets:
          type: array
          items:
            $ref: '#/components/schemas/controllers.SummaryMarket'
        message:
          type: string
        status:
          description: 'Whether the match is under way: pending, live, settled or cancelled. Can read live before the listed start, or while /events still lists the event as pending. A pending event never carries in-play prices.'
          type: string
    dto.MultiMarketDto:
      type: object
      properties:
        name:
          type: string
        odds:
          type: array
          items:
            $ref: '#/components/schemas/dto.Odds'
        updatedAt:
          type: string
    controllers.SummaryPayout:
      type: object
      properties:
        average:
          type: number
        best:
          type: number
    controllers.SummaryOutcomes:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/controllers.SummaryOutcome'
    controllers.EventResponse:
      type: object
      properties:
        away:
          type: string
        awayId:
          type: integer
        bookmakerIds:
          type: object
          additionalProperties:
            type: string
        bookmakers:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/dto.MultiMarketDto'
        date:
          type: string
        home:
          type: string
        homeId:
          type: integer
        id:
          type: integer
        league:
          $ref: '#/components/schemas/controllers.League'
        scores:
          $ref: '#/components/schemas/dto.Score'
        sport:
          $ref: '#/components/schemas/controllers.Sport'
        status:
          description: 'Whether the match is under way: pending, live, settled or cancelled. Can read live before the listed start, or while /events still lists the event as pending. A pending event never carries in-play prices.'
          type: string
        urls:
          type: object
          additionalProperties:
            type: string
    dto.Odds:
      type: object
      properties:
        '12':
          type: string
        1X:
          description: 'Specialty market fields

            Double Chance: 1X (home or draw), 12 (home or away), X2 (draw or away)'
          type: string
        X2:
          type: string
        away:
          type: string
        awayLink:
          type: string
        depthAway:
          type: string
        depthDraw:
          type: string
        depthHome:
          type: string
        depthLayAway:
          type: string
        depthLayDraw:
          type: string
        depthLayHome:
          type: string
        depthLayNo:
          description: Available liquidity to lay no. Yes/no markets only (currently Both Teams To Score on exchange-style books).
          type: string
        depthLayOver:
          description: Available liquidity to lay over. On yes/no markets this repeats depthLayYes, kept for compatibility.
          type: string
        depthLayUnder:
          description: Available liquidity to lay under. On yes/no markets this repeats depthLayNo, kept for compatibility.
          type: string
        depthLayYes:
          description: Available liquidity to lay yes. Yes/no markets only (currently Both Teams To Score on exchange-style books).
          type: string
        depthNo:
          description: Available liquidity to back no. Yes/no markets only (currently Both Teams To Score on exchange-style books).
          type: string
        depthOver:
          description: Available liquidity to back over. On yes/no markets this repeats depthYes, kept for compatibility.
          type: string
        depthUnder:
          description: Available liquidity to back under. On yes/no markets this repeats depthNo, kept for compatibility.
          type: string
        depthYes:
          description: Available liquidity to back yes. Yes/no markets only (currently Both Teams To Score on exchange-style books).
          type: string
        draw:
          type: string
        drawLink:
          type: string
        even:
          type: string
        exactly:
          description: 'Three-way corner lines only (Corners, Alternative Corners, 1st Half Corners): price for the count landing exactly on hdp. When present, Over and Under both lose on that number.'
          type: string
        hdp:
          type: number
        home:
          type: string
        homeLink:
          type: string
        label:
          type: string
        layAway:
          type: string
        layDraw:
          type: string
        layHome:
          type: string
        layNo:
          type: string
        layOver:
          type: string
        layUnder:
          type: string
        layYes:
          type: string
        max:
          type: integer
        neither:
          description: 'Corners Race: neither team reaches the target'
          type: string
        'no':
          type: string
        none:
          description: 'First Team To Score: none option'
          type: string
        odd:
          description: Odd/Even market
          type: string
        odds:
          description: Labeled markets (Half Time / Full Time, Correct Score) - single odds value per outcome
          type: string
        over:
          type: string
        under:
          type: string
        'yes':
          type: string
    controllers.HandicapMovement:
      type: object
      properties:
        away:
          type: number
        draw:
          type: number
        hdp:
          type: string
        home:
          type: number
        max:
          type: integer
        timestamp:
          type: integer
    controllers.Sport:
      type: object
      properties:
        name:
          type: string
          example: Football
        slug:
          type: string
          example: football
    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.SideInts:
      type: object
      description: Home/away pair of whole numbers (cricket wickets).
      properties:
        away:
          type: integer
          example: 9
        home:
          type: integer
          example: 6
    controllers.SummaryMarket:
      type: object
      properties:
        lines:
          type: array
          items:
            $ref: '#/components/schemas/controllers.SummaryLine'
        name:
          type: string
    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
    controllers.SummaryLine:
      type: object
      properties:
        books:
          type: integer
        exchanges:
          $ref: '#/components/schemas/controllers.SummaryExchanges'
        fairBooks:
          type: integer
        hdp:
          type:
          - number
          - 'null'
        main:
          type: boolean
        outcomes:
          $ref: '#/components/schemas/controllers.SummaryOutcomes'
        payout:
          $ref: '#/components/schemas/controllers.SummaryPayout'
    controllers.ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Error message
    controllers.SummaryExchangeQuote:
      type: object
      properties:
        best:
          type: number
        currency:
          type: string
        liquidity:
          type: number
        venue:
          type: string
    controllers.HandicapMovementsResponse:
      type: object
      properties:
        bookmaker:
          type: string
        eventid:
          type: string
        latest:
          $ref: '#/components/schemas/controllers.HandicapMovement'
        movements:
          type: array
          items:
            $ref: '#/components/schemas/controllers.HandicapMovement'
        opening:
          $ref: '#/components/schemas/controllers.HandicapMovement'
  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