realtimesportsapi-com Events API

openapi: 3.2.0
info:
  title: Realtimesportsapi Com Events API
  version: 1.0.0
  contact:
    name: Realtime Sports API support
    email: austin@elcodev.com
    url: https://www.realtimesportsapi.com/?utm_source=openapi
  license:
    name: Proprietary
    url: https://www.realtimesportsapi.com/terms?utm_source=openapi
  termsOfService: https://www.realtimesportsapi.com/terms?utm_source=openapi
  description: 'Operations tagged Events across 2 of this provider''s published API definitions: original.json, realtimesportsapi-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.realtimesportsapi.com/api/v1
  description: Production
security:
- BearerAuth: []
- ApiKeyHeader: []
tags:
- name: Events
  description: 'Games: lists, live games, single game, box score, win probability, game rosters'
paths:
  /sports/{sport}/leagues/{league}/events:
    get:
      operationId: listEvents
      tags:
      - Events
      summary: List events for a league
      description: Current and upcoming events (the provider's current scoreboard window). For a specific date range or week use the season schedule endpoint.
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: limit
        in: query
        required: false
        description: Maximum events to return (default 50).
        schema:
          type: integer
          example: 50
          default: 50
          minimum: 1
      - name: includeOdds
        in: query
        required: false
        description: Attach current betting odds (when available) to each event. Adds latency.
        schema:
          type: boolean
          example: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
  /sports/{sport}/leagues/{league}/events/live:
    get:
      operationId: listLiveEvents
      tags:
      - Events
      summary: List live events
      description: Events currently in progress (status.state = "in"). Returns an empty array when nothing is live. For continuous updates prefer webhooks or the WebSocket stream over tight polling.
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: includeOdds
        in: query
        required: false
        description: Attach current betting odds (when available) to each event. Adds latency.
        schema:
          type: boolean
          example: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
  /sports/{sport}/leagues/{league}/events/{eventId}:
    get:
      operationId: getEvent
      tags:
      - Events
      summary: Get an event
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: eventId
        in: path
        required: true
        description: Event (game) id, as returned by the events endpoints.
        schema:
          type: string
          example: '401772982'
      - name: includeOdds
        in: query
        required: false
        description: Attach current betting odds (when available) to each event. Adds latency.
        schema:
          type: boolean
          example: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Event'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Event not found (EVENT_NOT_FOUND).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
  /sports/{sport}/leagues/{league}/events/{eventId}/boxscore:
    get:
      operationId: getEventBoxScore
      tags:
      - Events
      summary: Get box score
      description: Team totals and player stats. Supported for basketball, soccer, baseball and football. Football players carry per-category stats (passing, rushing, receiving, defensive, kicking, returns) under `categories`.
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: eventId
        in: path
        required: true
        description: Event (game) id, as returned by the events endpoints.
        schema:
          type: string
          example: '401772982'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/BoxScore'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Box score not available, e.g. pre-game (BOXSCORE_NOT_AVAILABLE).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
  /sports/{sport}/leagues/{league}/events/{eventId}/winprobability:
    get:
      operationId: getEventWinProbability
      tags:
      - Events
      summary: Get win probability
      description: Per-play win probability series (join to plays via playId) plus drive summaries, where the source publishes them.
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: eventId
        in: path
        required: true
        description: Event (game) id, as returned by the events endpoints.
        schema:
          type: string
          example: '401772982'
      - name: drives
        in: query
        required: false
        description: Include drive summaries (default true).
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/WinProbability'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                      count:
                        type: integer
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Event summary not available (NOT_FOUND).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
  /sports/{sport}/leagues/{league}/events/{eventId}/roster:
    get:
      operationId: getEventRoster
      tags:
      - Events
      summary: Get game rosters
      description: Game-specific rosters with per-player flags (starter, didNotPlay, active). Published by the source at kickoff.
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: eventId
        in: path
        required: true
        description: Event (game) id, as returned by the events endpoints.
        schema:
          type: string
          example: '401772982'
      - name: team
        in: query
        required: false
        description: Return only this team id.
        schema:
          type: string
          example: '12'
      - name: starters
        in: query
        required: false
        description: Only starters.
        schema:
          type: boolean
          example: false
      - name: enrich
        in: query
        required: false
        description: Resolve athlete names, teams and positions for play participants (default true). Pass false for faster, id-only results.
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/GameRoster'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Game roster not published yet (ROSTER_NOT_PUBLISHED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
components:
  schemas:
    GameRoster:
      type: object
      properties:
        eventId:
          type: string
        teams:
          type: array
          items:
            type: object
            properties:
              team:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  abbreviation:
                    type: string
              homeAway:
                type: string
                example: home
                enum:
                - home
                - away
              players:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    shortName:
                      type: string
                    jersey:
                      type: string
                    position:
                      type: string
                    headshot:
                      type: string
                    starter:
                      type: boolean
                    didNotPlay:
                      type: boolean
                    active:
                      type: boolean
                    forPlayerId:
                      type: string
              summary:
                type: object
                properties:
                  total:
                    type: integer
                  starters:
                    type: integer
                  didNotPlay:
                    type: integer
    InningState:
      type: object
      properties:
        number:
          type: integer
          example: 5
        half:
          type:
          - string
          - 'null'
          example: bottom
          enum:
          - top
          - bottom
          - middle
          - end
        outs:
          type: integer
          example: 2
        balls:
          type: integer
          example: 3
        strikes:
          type: integer
          example: 1
        onFirst:
          type: boolean
          example: true
        onSecond:
          type: boolean
          example: false
        onThird:
          type: boolean
          example: true
      description: MLB only; absent for other leagues and before first pitch. half, the count and the runner flags are set while the game is live and null otherwise.
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: MISSING_TOKEN
            message:
              type: string
              example: Authorization required
            hint:
              type: string
              example: 'Use Authorization: Bearer <your-api-key> or X-API-Key: <your-api-key>.'
          required:
          - code
          - message
      required:
      - success
      - error
    EventStatus:
      type: object
      properties:
        state:
          type: string
          example: in
          enum:
          - pre
          - in
          - post
        completed:
          type: boolean
          example: false
        period:
          type: integer
          example: 2
        clock:
          type: string
          example: '5:23'
        detail:
          type: string
          example: 5:23 - 2nd Quarter
        halftime:
          type: boolean
          example: false
        firstHalfEnded:
          type: boolean
          example: false
        inning:
          $ref: '#/components/schemas/InningState'
    BoxScore:
      type: object
      properties:
        homeTeam:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            abbreviation:
              type: string
            score:
              type: integer
        awayTeam:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            abbreviation:
              type: string
            score:
              type: integer
        homePlayers:
          type: array
          items:
            type: object
            additionalProperties: true
            description: 'Basketball/soccer/baseball: flat stat keys (points, rebounds, assists, minutes, ...). Football: per-category stats under `categories`.'
        awayPlayers:
          type: array
          items:
            type: object
            additionalProperties: true
        periodScores:
          type: object
          properties:
            home:
              type: array
              items:
                type: integer
            away:
              type: array
              items:
                type: integer
    EventTeam:
      type: object
      properties:
        id:
          type: string
          example: '12'
        name:
          type: string
          example: Kansas City Chiefs
        abbreviation:
          type: string
          example: KC
        logo:
          type:
          - string
          - 'null'
          description: Team logo URL when available.
        color:
          type: string
          example: e31837
        alternateColor:
          type: string
          example: ffb612
        winner:
          type: boolean
          example: false
        record:
          type: string
          example: 3-1
        score:
          type: integer
          example: 14
    WinProbability:
      type: object
      properties:
        eventId:
          type: string
        winProbability:
          type: array
          items:
            type: object
            properties:
              playId:
                type: string
              homeWinPercentage:
                type: number
                example: 0.62
              awayWinPercentage:
                type: number
                example: 0.38
              tiePercentage:
                type: number
                example: 0
        drives:
          type: array
          items:
            type: object
            additionalProperties: true
            description: Drive summaries (omitted when drives=false).
    Event:
      type: object
      properties:
        id:
          type: string
          example: '401772982'
        uid:
          type: string
        name:
          type: string
          example: Kansas City Chiefs at Baltimore Ravens
        shortName:
          type: string
          example: KC @ BAL
        date:
          type: string
          example: 2026-10-04T17:00Z
          format: date-time
        status:
          $ref: '#/components/schemas/EventStatus'
        homeTeam:
          $ref: '#/components/schemas/EventTeam'
        awayTeam:
          $ref: '#/components/schemas/EventTeam'
        competition:
          type: object
          properties:
            attendance:
              type: integer
            neutralSite:
              type: boolean
            conferenceCompetition:
              type: boolean
            divisionCompetition:
              type: boolean
            playByPlayAvailable:
              type: boolean
            highlightsAvailable:
              type: boolean
        venue:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
            name:
              type: string
            city:
              type: string
            state:
              type: string
            indoor:
              type: boolean
            grass:
              type: boolean
        notes:
          type: array
          items:
            type: string
        season:
          type: object
          properties:
            year:
              type: integer
              example: 2026
            displayName:
              type: string
              example: '2026'
            type:
              type: object
              properties:
                id:
                  type: string
                  example: '2'
                name:
                  type: string
                  example: Regular Season
                abbreviation:
                  type: string
                  example: reg
            week:
              type: object
              properties:
                number:
                  type: integer
                  example: 5
                startDate:
                  type: string
                endDate:
                  type: string
                text:
                  type: string
                  example: Week 5
        broadcasts:
          type: array
          items:
            type: object
            properties:
              network:
                type: string
                example: CBS
              type:
                type: string
                example: TV
        officials:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              fullName:
                type: string
              displayName:
                type: string
              order:
                type: integer
              position:
                type: string
        odds:
          allOf:
          - $ref: '#/components/schemas/Odds'
          description: Present only when includeOdds=true and odds are available.
    RateLimit:
      type: object
      properties:
        limit:
          type: integer
          example: 10000
          description: Calls included this month.
        remaining:
          type: integer
          example: 9876
          description: Calls remaining this month (approximate; updated asynchronously).
        reset:
          type: integer
          example: 1767225600000
          description: Quota reset time, Unix epoch milliseconds.
    Odds:
      type: object
      properties:
        provider:
          type: string
          description: Name of the single source book.
        spread:
          type:
          - object
          - 'null'
          properties:
            line:
              type: number
              example: -3.5
            home:
              type: number
              example: -110
            away:
              type: number
              example: -110
        moneyline:
          type:
          - object
          - 'null'
          properties:
            home:
              type: number
              example: -180
            away:
              type: number
              example: 150
        overUnder:
          type:
          - object
          - 'null'
          properties:
            total:
              type: number
              example: 48.5
            over:
              type: number
              example: -110
            under:
              type: number
              example: -110
        updatedAt:
          type: string
          format: date-time
  responses:
    RateLimitExceeded:
      description: 'Too many requests: either the monthly quota is exhausted (code RATE_LIMIT_EXCEEDED; upgrade or enable overage) or the plan''s per-second rate was exceeded (code RATE_LIMIT_PER_SECOND; Free 1/s, Starter 5/s, Growth 10/s, Pro 20/s, Scale 100/s). Wait for `Retry-After` seconds.'
      headers:
        Retry-After:
          description: Seconds until you may retry.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 'Missing, malformed, unknown or expired API key (codes: MISSING_TOKEN, USER_NOT_FOUND, TRIAL_EXPIRED).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected error. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key from the dashboard: `Authorization: Bearer <api key>`. Keys are opaque strings, not JWTs.'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative to the Authorization header (useful behind proxies that strip Authorization).
externalDocs:
  description: Guides, WebSocket and webhook docs
  url: https://www.realtimesportsapi.com/docs?utm_source=openapi
x-refined-from:
- original.json
- realtimesportsapi-com-openapi.json