openapi: 3.0.3
info:
  title: TheRundown Sports V1 Delta V2 Stats API
  version: 2.0.0
  description: 'Real-time and historical sports betting data, odds, lines, and statistics across major North American and international sports leagues.


    ## Authentication

    All endpoints (except `/sports` and `/affiliates`) require authentication. Pass your API key using one of:

    - **Query parameter**: `?key=YOUR_API_KEY`

    - **Header**: `X-Therundown-Key: YOUR_API_KEY`

    ## Off-the-Board Sentinel Value

    The value **0.0001** indicates a line is "off the board" — the sportsbook has temporarily removed pricing (e.g., pending injury news). This is NOT an error. Display as "Off Board" or "N/A" in your UI.


    ## Rate Limiting

    Requests are rate-limited per API key tier. Check response headers for current limits.


    ## Data Updates

    - Live odds update in real-time during games

    - Use delta endpoints for efficient polling of changes

    - WebSocket connections available for streaming updates


    ## V1 vs V2

    V2 endpoints use market-based data structures (market_id, participants, line prices). V1 endpoints use legacy line-based structures (moneyline, spread, total objects). V2 is recommended for new integrations.

    '
  contact:
    name: TheRundown API Support
    url: https://therundown.io
    email: support@therundown.io
  termsOfService: https://therundown.io/terms
servers:
- url: https://therundown.io
  description: Production
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
tags:
- name: V2 Stats
  description: Team and player statistics (V2)
paths:
  /api/v2/events/{eventID}/stats:
    get:
      operationId: v2GetStatsByEvent
      tags:
      - V2 Stats
      summary: Get team game stats for an event
      parameters:
      - $ref: '#/components/parameters/EventIDPath'
      - name: stats_ids
        in: query
        schema:
          type: string
        description: Comma-separated stat IDs (max 12)
      - name: team_id
        in: query
        schema:
          type: integer
        description: Filter by team ID
      responses:
        '200':
          description: Team game stats
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TeamGameStatResponse'
              example:
              - team:
                  team_id: 11
                  name: Atlanta Hawks
                  mascot: Hawks
                  abbreviation: ATL
                meta:
                  complete: true
                stats:
                - team_id: 11
                  stat_id: 1242
                  stat:
                    id: 1242
                    name: avgRebounds
                    display_name: Rebounds Per Game
                    abbreviation: REB
                    sport_id: 4
                  event_id: 5a0c9d5d8d3e2c0001a1b2c3
                  value: '42'
                - team_id: 11
                  stat_id: 1243
                  stat:
                    id: 1243
                    name: assistTurnoverRatio
                    display_name: Assist To Turnover Ratio
                    abbreviation: AST/TO
                    sport_id: 4
                  event_id: 5a0c9d5d8d3e2c0001a1b2c3
                  value: '2.26'
  /api/v2/events/{eventID}/players/stats:
    get:
      operationId: v2GetPlayerStatsByEvent
      tags:
      - V2 Stats
      summary: Get player game stats for an event
      parameters:
      - $ref: '#/components/parameters/EventIDPath'
      - name: stats_ids
        in: query
        schema:
          type: string
        description: Comma-separated stat IDs (max 12)
      - name: player_ids
        in: query
        schema:
          type: string
        description: Comma-separated player IDs (max 6)
      responses:
        '200':
          description: Player game stats
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlayerGameStatResponse'
              example:
              - player:
                  id: 16627
                  sport_id: 4
                  team_id: 11
                  first_name: Trae
                  last_name: Young
                  display_name: Trae Young
                  jersey: '11'
                  position: Guard
                  position_abbreviation: G
                meta:
                  complete: true
                stats:
                - stat:
                    id: 1288
                    name: points
                    display_name: Points
                    abbreviation: PTS
                    sport_id: 4
                  value: '28'
                - stat:
                    id: 1289
                    name: assists
                    display_name: Assists
                    abbreviation: AST
                    sport_id: 4
                  value: '11'
  /api/v2/stats:
    get:
      operationId: v2GetAllStats
      tags:
      - V2 Stats
      summary: List all stat definitions
      parameters:
      - name: id
        in: query
        schema:
          type: integer
        description: Filter by stat ID
      - name: sport_id
        in: query
        schema:
          type: integer
        description: Filter by sport ID
      responses:
        '200':
          description: Stat definitions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StatDefinition'
              example:
              - id: 1
                name: completionPct
                display_name: Completion Percentage
                abbreviation: CMP%
                description: The percentage of completed passes.
                sport_id: 2
              - id: 2
                name: completions
                display_name: Completions
                abbreviation: CMP
                description: The times a player completes a pass to another player.
                sport_id: 2
              - id: 1242
                name: avgRebounds
                display_name: Rebounds Per Game
                abbreviation: REB
                description: The average rebounds per game.
                sport_id: 4
components:
  schemas:
    PlayerNormalized:
      type: object
      properties:
        id:
          type: integer
        sport_id:
          type: integer
        team_id:
          type: integer
        updated_at:
          type: string
          format: date-time
          nullable: true
        first_name:
          type: string
        last_name:
          type: string
        display_name:
          type: string
        weight:
          type: number
        height:
          type: number
        display_weight:
          type: string
        display_height:
          type: string
        age:
          type: integer
        date_of_birth:
          type: string
        slug:
          type: string
        jersey:
          type: string
        position:
          type: string
        position_abbreviation:
          type: string
        debut_year:
          type: integer
        birth_place_city:
          type: string
        birth_place_country:
          type: string
        experience_years:
          type: integer
        active:
          type: boolean
        status:
          type: string
        bats:
          type: string
          description: MLB only — batting side
        throws:
          type: string
          description: MLB only — throwing arm
    TeamGameStats:
      type: object
      properties:
        team_id:
          type: integer
          nullable: true
        team:
          $ref: '#/components/schemas/TeamNormalized'
        stat_id:
          type: integer
          nullable: true
        stat:
          $ref: '#/components/schemas/StatDefinition'
        event_id:
          type: string
        value:
          type: string
    StatDefinition:
      type: object
      properties:
        id:
          type: integer
          nullable: true
        name:
          type: string
        category:
          type: string
        display_name:
          type: string
        abbreviation:
          type: string
        description:
          type: string
        sport_id:
          type: integer
    Conference:
      type: object
      properties:
        conference_id:
          type: integer
        sport_id:
          type: integer
        name:
          type: string
    StatsMeta:
      type: object
      properties:
        complete:
          type: boolean
    TeamGameStatResponse:
      type: object
      properties:
        team:
          $ref: '#/components/schemas/TeamNormalized'
        meta:
          $ref: '#/components/schemas/StatsMeta'
        stats:
          type: array
          items:
            $ref: '#/components/schemas/TeamGameStats'
    TeamNormalized:
      type: object
      properties:
        team_id:
          type: integer
        name:
          type: string
        mascot:
          type: string
        abbreviation:
          type: string
        record:
          type: string
        is_home:
          type: boolean
        is_away:
          type: boolean
        ranking:
          type: integer
          nullable: true
        conference:
          $ref: '#/components/schemas/Conference'
        division:
          $ref: '#/components/schemas/Division'
    PlayerGameStats:
      type: object
      properties:
        event_id:
          type: string
        player_id:
          type: integer
          nullable: true
        player:
          $ref: '#/components/schemas/PlayerNormalized'
        stat_id:
          type: integer
          nullable: true
        stat:
          $ref: '#/components/schemas/StatDefinition'
        value:
          type: string
        updated_at:
          type: string
          format: date-time
          nullable: true
    Division:
      type: object
      properties:
        division_id:
          type: integer
        conference_id:
          type: integer
        sport_id:
          type: integer
        name:
          type: string
    PlayerGameStatResponse:
      type: object
      properties:
        player:
          $ref: '#/components/schemas/PlayerNormalized'
        meta:
          $ref: '#/components/schemas/StatsMeta'
        stats:
          type: array
          items:
            $ref: '#/components/schemas/PlayerGameStats'
  parameters:
    EventIDPath:
      name: eventID
      in: path
      required: true
      schema:
        type: string
      description: Canonical V2 event ID from the `event_id` field returned by event endpoints
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: API key as query parameter
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Therundown-Key
      description: API key as request header