openapi: 3.1.0
info:
  title: Sportsbook Betting Analysis Odds API
  description: Sportsbook API provides real-time betting odds data from major US sportsbooks including FanDuel, DraftKings, BetMGM, Kalshi, theScore, Fanatics, BetRivers, Polymarket, Bovada, and BetOnline. The API covers NFL, NBA, MLB, NHL, NCAA football, NCAA basketball, soccer, and more with spreads, moneylines, totals, halves, quarters, props, and futures markets. Odds update once per minute with positive EV, arbitrage, and middle opportunity detection.
  version: '1.0'
  contact:
    url: https://sportsbookapi.com/
  termsOfService: https://sportsbookapi.com/terms
servers:
- url: https://api.sportsbookapi.com
  description: Production server
security:
- rapidApiKey: []
tags:
- name: Odds
paths:
  /v1/odds:
    get:
      operationId: getOdds
      summary: Get Odds
      description: Retrieve real-time betting odds from multiple sportsbooks for a given sport and league.
      tags:
      - Odds
      parameters:
      - name: sport
        in: query
        required: true
        description: Sport to retrieve odds for (football, basketball, baseball, hockey, soccer)
        schema:
          type: string
          enum:
          - football
          - basketball
          - baseball
          - hockey
          - soccer
      - name: league
        in: query
        required: false
        description: League filter (NFL, NBA, MLB, NHL, NCAAF, NCAAB, EPL, MLS)
        schema:
          type: string
      - name: market
        in: query
        required: false
        description: Betting market type
        schema:
          type: string
          enum:
          - spread
          - moneyline
          - total
          - prop
          - future
      - name: bookmaker
        in: query
        required: false
        description: Filter by specific sportsbook
        schema:
          type: string
      responses:
        '200':
          description: Odds data from multiple sportsbooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OddsResponse'
        '401':
          description: Unauthorized - missing or invalid API key
        '429':
          description: Rate limit exceeded
  /v1/odds/{eventId}:
    get:
      operationId: getEventOdds
      summary: Get Event Odds
      description: Retrieve all odds for a specific event across all sportsbooks and markets.
      tags:
      - Odds
      parameters:
      - name: eventId
        in: path
        required: true
        description: Unique event identifier
        schema:
          type: string
      responses:
        '200':
          description: Event odds details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventOdds'
        '404':
          description: Event not found
components:
  schemas:
    OddsResponse:
      type: object
      properties:
        sport:
          type: string
          description: Sport name
        league:
          type: string
          description: League abbreviation
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventOdds'
    BookmakerOdds:
      type: object
      properties:
        bookmaker:
          type: string
          description: Sportsbook name
        homeOdds:
          type: number
          format: float
          description: Home team or over odds in American format
        awayOdds:
          type: number
          format: float
          description: Away team or under odds in American format
        line:
          type: number
          format: float
          description: Point spread or total points line
        lastUpdated:
          type: string
          format: date-time
    EventOdds:
      type: object
      properties:
        eventId:
          type: string
        homeTeam:
          type: string
        awayTeam:
          type: string
        startTime:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - scheduled
          - live
          - final
        markets:
          type: array
          items:
            $ref: '#/components/schemas/MarketOdds'
    MarketOdds:
      type: object
      properties:
        market:
          type: string
          description: Market type (spread, moneyline, total, prop)
        period:
          type: string
          description: Game period (fullgame, firsthalf, firstquarter)
        bookmakers:
          type: array
          items:
            $ref: '#/components/schemas/BookmakerOdds'
  securitySchemes:
    rapidApiKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key