Big Ball Sports API API

{
  "openapi": "3.1.0",
  "info": {
    "title": "Big Ball Sports API",
    "description": "Unified sports data API (REST + GraphQL + WebSocket) aggregating 19+\nfree-tier upstream sources and 10 MCP scrapers behind a Stripe-style\ngateway. Every response carries a confidence score and source attribution\nso callers can render appropriate caveats.\n\n## Pagination\n\nList endpoints page with `?limit=` and `?offset=`. `?page=N` is an alias\nfor `?offset=(N-1)*limit`, resolved against that endpoint's own `limit`\ndefault, so `?page=2` and `?offset=<limit>` are the same request. When both\nare sent, `?offset=` wins; it is the more specific instruction.\n\nEndpoints that return a single page (leaderboards, one team's form, one\nplayer's stat line) document a `limit` and no `offset`. On those, `?page=`\nis **rejected with a 400** naming `?limit=` rather than accepted and\nignored, so a paging attempt can never silently look like it worked.\n",
    "version": "1.0.0",
    "contact": {
      "email": "support@bigballsdata.com"
    }
  },
  "servers": [
    {
      "url": "https://api.bigballsdata.com",
      "description": "Production"
    },
    {
      "url": "https://bbsgateway-production.up.railway.app",
      "description": "Production (Railway direct, fallback)"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Big Ball Sports API key. Or pass via `Authorization: Bearer <key>`."
      },
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "bbs_<env>_<32hex>"
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 255
        },
        "description": "Stripe-style idempotency token. Retries with the same key within\n24h replay the original response without re-running the handler.\n"
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limited (`429`). Two causes share `error.code: rate_limited` and are\ntold apart by `error.message` and headers:\n  - **Quota exhaustion** (per-minute or per-day cap). The envelope is\n    enriched: `suggested_fix` names the next tier and its cap, and\n    `meta.current_usage` + `meta.upgrade_path` carry live usage and the\n    upgrade target. `X-RateLimit-Limit/-Remaining/-Reset` are present.\n  - **4xx circuit breaker** (sustained high 4xx rate: malformed\n    requests, or ignoring Retry-After and hammering past quota; key in\n    cooldown). Carries `X-RateLimit-4xx-Cooldown`; no `upgrade_path`.\nAdditive: existing parsers keying on `error.code`, `error.message`,\n`docs_url`, `support`, `meta.request_id` are unaffected.\n`X-RateLimit-Limit/-Remaining/-Reset` are returned on every authenticated\nresponse (2xx/4xx/5xx), not only on 429s, so clients can self-throttle.\n",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the limit (or 4xx cooldown) resets.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Limit": {
            "description": "Effective request cap (tighter bucket).",
            "schema": {
              "type": "string"
            }
          },
          "X-RateLimit-Remaining": {
            "description": "Requests remaining in the tighter bucket.",
            "schema": {
              "type": "string"
            }
          },
          "X-RateLimit-Reset": {
            "description": "Unix seconds at which the tighter bucket resets.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-4xx-Cooldown": {
            "description": "Seconds remaining on the 4xx breaker cooldown (only on breaker 429s).",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "example": "rate_limited"
                    },
                    "message": {
                      "type": "string",
                      "example": "Daily quota exhausted (250 of 250 requests used)"
                    }
                  }
                },
                "suggested_fix": {
                  "type": "string",
                  "description": "Quota 429 only, tier-aware upgrade guidance.",
                  "example": "Pace requests using the Retry-After and X-RateLimit-* response headers. Handling guide: https://bigballsdata.com/docs/rate-limits. If you're regularly at this ceiling, the solo plan is $19/month and raises your daily limit to 10,000/day: https://bigballsdata.com/dashboard/billing?plan=solo."
                },
                "docs_url": {
                  "type": "string"
                },
                "support": {
                  "type": "object"
                },
                "meta": {
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "limiting_bucket": {
                      "type": "string",
                      "enum": [
                        "minute",
                        "day"
                      ],
                      "description": "Quota 429 only. WHICH of the two buckets refused this\nrequest, and therefore which cap `error.message` and\n`suggested_fix` are about. `current_usage` reports both\nbuckets without saying which one was binding; this says.\n\nUse it for backoff: a `minute` refusal clears within\nseconds, a `day` refusal not until the UTC rollover.\n`Retry-After` already carries the right wait in seconds.\n",
                      "example": "minute"
                    },
                    "current_usage": {
                      "type": "object",
                      "description": "Quota 429 only, live per-bucket usage.",
                      "properties": {
                        "minute": {
                          "type": "object",
                          "properties": {
                            "used": {
                              "type": "integer"
                            },
                            "limit": {
                              "type": "integer"
                            },
                            "resets_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "day": {
                          "type": "object",
                          "properties": {
                            "used": {
                              "type": "integer"
                            },
                            "limit": {
                              "type": "integer"
                            },
                            "resets_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        }
                      }
                    },
                    "upgrade_path": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/UpgradePath"
                        }
                      ],
                      "description": "The upgrade target for THIS 429: the next tier up the\nladder, because the caller's problem is volume.\n`recommended_tier` is null at the top self-serve tier.\n"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "Service temporarily unavailable (`503`). Returned when a backing query\nexceeds the endpoint's `statement_timeout` (Postgres cancels it) instead\nof holding the connection for seconds. Transient under heavy load;\nretry after a short delay. Standard error envelope with\n`error.code = upstream_unavailable`.\n",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "example": "upstream_unavailable"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "docs_url": {
                  "type": "string"
                },
                "support": {
                  "type": "object"
                },
                "meta": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "NbaBoxScoreEntry": {
        "type": "object",
        "description": "One player's line in an NBA game box score. Counting stats are integers and percentages are decimal strings as stored. `minutes` is WHOLE minutes, rounded; `seconds_played` carries the exact total when the feed supplies seconds and is null when it supplied only a whole minute. Corrected 2026-10-23: `minutes` was declared a string here, but the column is a smallint and the served value has always been a JSON number (verified against production). Rows written before that date read `seconds_played` null and carry a `minutes` value that was truncated rather than rounded, so it can read one minute low until the game is re-ingested.",
        "properties": {
          "player_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Null when the upstream player is not yet bridged to a BigBalls player"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "starter": {
            "type": "boolean",
            "nullable": true,
            "description": "Null for games with no pre-tip lineup coverage"
          },
          "minutes": {
            "type": "integer",
            "nullable": true,
            "description": "Whole minutes played, ROUNDED (half up) from the exact value. Agrees with /v1/stored/matches/{id}/stats, which is authoritative for minutes."
          },
          "seconds_played": {
            "type": "integer",
            "nullable": true,
            "description": "Exact total seconds played, as supplied. Null means the feed gave a whole minute and nothing finer, NOT that the player played no seconds; it is never minutes x 60."
          },
          "points": {
            "type": "integer",
            "nullable": true
          },
          "rebounds": {
            "type": "integer",
            "nullable": true
          },
          "offensive_rebounds": {
            "type": "integer",
            "nullable": true
          },
          "defensive_rebounds": {
            "type": "integer",
            "nullable": true
          },
          "assists": {
            "type": "integer",
            "nullable": true
          },
          "steals": {
            "type": "integer",
            "nullable": true
          },
          "blocks": {
            "type": "integer",
            "nullable": true
          },
          "turnovers": {
            "type": "integer",
            "nullable": true
          },
          "fouls": {
            "type": "integer",
            "nullable": true
          },
          "plus_minus": {
            "type": "integer",
            "nullable": true
          },
          "field_goals_made": {
            "type": "integer",
            "nullable": true
          },
          "field_goals_attempted": {
            "type": "integer",
            "nullable": true
          },
          "field_goal_pct": {
            "type": "string",
            "nullable": true
          },
          "three_pointers_made": {
            "type": "integer",
            "nullable": true
          },
          "three_pointers_attempted": {
            "type": "integer",
            "nullable": true
          },
          "three_point_pct": {
            "type": "string",
            "nullable": true
          },
          "free_throws_made": {
            "type": "integer",
            "nullable": true
          },
          "free_throws_attempted": {
            "type": "integer",
            "nullable": true
          },
          "free_throw_pct": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "SingleMatchPrediction": {
        "type": "object",
        "description": "Latest stored prediction for one match. Check valid_until and expired before use.",
        "required": [
          "match_id",
          "prediction_type",
          "model_version",
          "valid_until",
          "expired",
          "generated_at"
        ],
        "properties": {
          "match_id": {
            "type": "string",
            "format": "uuid"
          },
          "prediction_type": {
            "type": "string",
            "enum": [
              "match_result",
              "value_prop"
            ]
          },
          "home_team": {
            "type": "string",
            "nullable": true
          },
          "away_team": {
            "type": "string",
            "nullable": true
          },
          "home_win_probability": {
            "type": "number",
            "nullable": true
          },
          "draw_probability": {
            "type": "number",
            "nullable": true
          },
          "away_win_probability": {
            "type": "number",
            "nullable": true
          },
          "home_elo": {
            "type": "number",
            "nullable": true
          },
          "away_elo": {
            "type": "number",
            "nullable": true
          },
          "model_version": {
            "type": "string"
          },
          "confidence": {
            "type": "number",
            "nullable": true
          },
          "valid_until": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "expired": {
            "type": "boolean",
            "nullable": true,
            "description": "Null means the prediction has no stated expiry."
          },
          "expired_days": {
            "type": "number",
            "nullable": true
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "kickoff_utc": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "group": {
            "type": "string",
            "nullable": true
          },
          "value_bet": {
            "type": "boolean",
            "nullable": true
          },
          "best_side": {
            "type": "string",
            "nullable": true
          },
          "elo_prob": {
            "type": "number",
            "nullable": true
          },
          "market_prob": {
            "type": "number",
            "nullable": true
          },
          "edge": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "SingleMatchPredictionResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SingleMatchPrediction"
          },
          "meta": {
            "type": "object",
            "required": [
              "returned",
              "expired",
              "expiry_unknown",
              "as_of"
            ],
            "properties": {
              "returned": {
                "type": "integer",
                "enum": [
                  1
                ]
              },
              "expired": {
                "type": "integer"
              },
              "expiry_unknown": {
                "type": "integer"
              },
              "as_of": {
                "type": "string",
                "format": "date-time"
              },
              "stale": {
                "type": "boolean",
                "description": "Present when the prediction is expired."
              },
              "message": {
                "type": "string",
                "description": "Present when the prediction is expired."
              }
            }
          }
        }
      },
      "UnifiedNbaTeamGame": {
        "type": "object",
        "required": [
          "id",
          "archive_team_id",
          "name",
          "short_name",
          "logo_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Canonical team UUID."
          },
          "archive_team_id": {
            "type": "string",
            "nullable": true,
            "description": "Original archive participant ID; null on match-only rows."
          },
          "name": {
            "type": "string"
          },
          "short_name": {
            "type": "string",
            "nullable": true
          },
          "logo_url": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "UnifiedNbaMatch": {
        "type": "object",
        "description": "NBA's additive v1 match shape. It preserves the ordinary Match fields, adds archive identity/statistics, and preserves a date-only historical game as midnight UTC plus time_precision=date. The marker explicitly says that the time component is not a known tip-off.",
        "required": [
          "id",
          "sport",
          "league",
          "season",
          "game_date",
          "kickoff_utc",
          "time_precision",
          "status",
          "home",
          "away"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "sport": {
            "type": "string",
            "enum": [
              "basketball"
            ]
          },
          "league": {
            "type": "string",
            "enum": [
              "NBA"
            ]
          },
          "archive_game_id": {
            "type": "string",
            "nullable": true
          },
          "match_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "season": {
            "type": "integer"
          },
          "season_type": {
            "type": "string"
          },
          "game_date": {
            "type": "string",
            "format": "date"
          },
          "kickoff_utc": {
            "type": "string",
            "format": "date-time"
          },
          "time_precision": {
            "type": "string",
            "enum": [
              "date",
              "timestamp"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/MatchStatus"
          },
          "home": {
            "$ref": "#/components/schemas/UnifiedNbaTeamGame"
          },
          "away": {
            "$ref": "#/components/schemas/UnifiedNbaTeamGame"
          },
          "score": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/MatchScore"
              },
              {
                "type": "null"
              }
            ]
          },
          "linescore": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Linescore"
              },
              {
                "type": "null"
              }
            ]
          },
          "attendance": {
            "type": [
              "integer",
              "null"
            ]
          },
          "broadcast": {
            "type": [
              "string",
              "null"
            ]
          },
          "round": {
            "type": [
              "string",
              "null"
            ]
          },
          "has_odds": {
            "type": "boolean"
          },
          "archive_stats": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          }
        }
      },
      "NbaGameTeamBox": {
        "type": "object",
        "description": "One team's box score on an NBA game row. `oreb` and `dreb` are stored team totals and always satisfy `oreb + dreb = reb` when present; they are not derived from the play-by-play log.",
        "properties": {
          "team_id": {
            "type": "string",
            "nullable": true,
            "description": "Upstream numeric team id, stable across seasons. Not a BBS team UUID."
          },
          "abbreviation": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "matchup": {
            "type": "string",
            "nullable": true
          },
          "wl": {
            "type": "string",
            "nullable": true,
            "enum": [
              "W",
              "L",
              null
            ]
          },
          "pts": {
            "type": "integer",
            "nullable": true
          },
          "fgm": {
            "type": "integer",
            "nullable": true
          },
          "fga": {
            "type": "integer",
            "nullable": true
          },
          "fg_pct": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Exact decimal ratio. PostgreSQL numeric values may serialize as JSON strings (for example, '0.455')."
          },
          "fg3m": {
            "type": "integer",
            "nullable": true
          },
          "fg3a": {
            "type": "integer",
            "nullable": true
          },
          "fg3_pct": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Exact decimal ratio. PostgreSQL numeric values may serialize as a JSON string."
          },
          "ftm": {
            "type": "integer",
            "nullable": true
          },
          "fta": {
            "type": "integer",
            "nullable": true
          },
          "ft_pct": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Exact decimal ratio. PostgreSQL numeric values may serialize as a JSON string."
          },
          "reb": {
            "type": "integer",
            "nullable": true,
            "description": "Total rebounds."
          },
          "oreb": {
            "type": "integer",
            "nullable": true,
            "description": "Offensive rebounds. Complete for the 1985-86 season onward; null for 1984-85 and earlier, where the split was not recorded. A 0 is a real zero, not a missing value."
          },
          "dreb": {
            "type": "integer",
            "nullable": true,
            "description": "Defensive rebounds. Same coverage boundary as `oreb`."
          },
          "ast": {
            "type": "integer",
            "nullable": true
          },
          "stl": {
            "type": "integer",
            "nullable": true
          },
          "blk": {
            "type": "integer",
            "nullable": true
          },
          "tov": {
            "type": "integer",
            "nullable": true
          }
        }
      },
      "NbaReboundSplitMeta": {
        "type": "object",
        "description": "Self-teaching disclosure of what `oreb`/`dreb` are and where they stop, returned on every /v1/nba/games response.",
        "properties": {
          "data_type": {
            "type": "string",
            "example": "stored_team_totals"
          },
          "coverage": {
            "type": "string",
            "description": "Which seasons carry the split."
          },
          "semantics": {
            "type": "string",
            "description": "What the numbers mean and how they were NOT produced."
          },
          "known_gap": {
            "type": "string",
            "description": "A season absent from this relation on every field, not just rebounds."
          }
        }
      },
      "NbaTeamSeasonAverage": {
        "type": "object",
        "description": "One team's season averages for ONE SLICE of the team cube. The grain is\n(season, season_type, category, stat_type), not one row per season: the\nsame team-season appears once per populated slice.\n\n`stats` is an OPEN OBJECT on purpose. The key set differs per\n(category, stat_type) because the upstream dashboards differ - 486\ndistinct keys across the 1,290 rows we hold - so flattening them into a\nfixed shape would invent nulls for every combination that does not carry\nthem. Values are JSON numbers except `play_type` and `type_grouping`,\nwhich are strings. Vendor-internal join ids are removed before the\nresponse is built.\n",
        "properties": {
          "team_id": {
            "type": "string",
            "format": "uuid",
            "description": "BigBalls team id."
          },
          "season": {
            "type": "integer",
            "example": 2025,
            "description": "Season LABEL: the year the season starts in."
          },
          "season_type": {
            "type": "string",
            "example": "regular",
            "description": "`regular` or `playoffs`. Only `regular` is populated today."
          },
          "category": {
            "type": "string",
            "example": "tracking",
            "description": "Cube dimension: general, clutch, tracking, playtype, shooting, shotdashboard or hustle."
          },
          "stat_type": {
            "type": "string",
            "example": "drives",
            "description": "Cube dimension inside the category. The EMPTY STRING is a real value, and it is the only one the `hustle` category uses, so `?stat_type=` selects that slice.\n"
          },
          "stats": {
            "type": "object",
            "additionalProperties": true,
            "description": "The slice's statistics. Key set varies by (category, stat_type)."
          }
        }
      },
      "NbaPlayerSeasonAverage": {
        "type": "object",
        "description": "One player's per-game averages for one regular season, as the vendor\npublishes them. Numeric fields are JSON numbers. Every column is\npopulated on every row we hold, so a `0` means the player really did\nrecord none of that stat per game; it is not a placeholder for\n\"unknown\".\n",
        "properties": {
          "player_id": {
            "type": "string",
            "format": "uuid",
            "description": "BigBalls player id."
          },
          "season": {
            "type": "integer",
            "example": 2025,
            "description": "Season LABEL: the year the season starts in."
          },
          "games_played": {
            "type": "integer",
            "nullable": true
          },
          "min": {
            "type": "string",
            "nullable": true,
            "example": "36:12",
            "description": "Average minutes per game as \"MM:SS\". This is a STRING because the vendor writes it as one; we do not convert it to a decimal, because that would be a number we invented published under the vendor's name.\n"
          },
          "pts": {
            "type": "number",
            "nullable": true,
            "description": "Points per game."
          },
          "ast": {
            "type": "number",
            "nullable": true,
            "description": "Assists per game."
          },
          "reb": {
            "type": "number",
            "nullable": true,
            "description": "Total rebounds per game."
          },
          "oreb": {
            "type": "number",
            "nullable": true,
            "description": "Offensive rebounds per game."
          },
          "dreb": {
            "type": "number",
            "nullable": true,
            "description": "Defensive rebounds per game."
          },
          "stl": {
            "type": "number",
            "nullable": true,
            "description": "Steals per game."
          },
          "blk": {
            "type": "number",
            "nullable": true,
            "description": "Blocks per game."
          },
          "turnover": {
            "type": "number",
            "nullable": true,
            "description": "Turnovers per game."
          },
          "pf": {
            "type": "number",
            "nullable": true,
            "description": "Personal fouls per game."
          },
          "fga": {
            "type": "number",
            "nullable": true
          },
          "fgm": {
            "type": "number",
            "nullable": true
          },
          "fg_pct": {
            "type": "number",
            "nullable": true,
            "description": "Field goal percentage as a ratio (0.576), not a percentage."
          },
          "fg3a": {
            "type": "number",
            "nullable": true
          },
          "fg3m": {
            "type": "number",
            "nullable": true
          },
          "fg3_pct": {
            "type": "number",
            "nullable": true,
            "description": "Three-point percentage as a ratio."
          },
          "fta": {
            "type": "number",
            "nullable": true
          },
          "ftm": {
            "type": "number",
            "nullable": true
          },
          "ft_pct": {
            "type": "number",
            "nullable": true,
            "description": "Free throw percentage as a ratio."
          }
        }
      },
      "NbaPlayerAdvancedSeason": {
        "type": "object",
        "description": "One player's advanced aggregates for one season and season type.\nPercentage-style fields are ratios (0.663), not percentages, except the\nturnover rates and `ast_ratio`, which the vendor publishes on a 0-100\nscale. `e_*` variants are the vendor's estimated counterparts to the\ncolumn of the same name.\n",
        "properties": {
          "player_id": {
            "type": "string",
            "format": "uuid"
          },
          "season": {
            "type": "integer",
            "example": 2025
          },
          "season_type": {
            "type": "string",
            "enum": [
              "regular",
              "playoffs"
            ]
          },
          "games_played": {
            "type": "integer",
            "nullable": true
          },
          "wins": {
            "type": "integer",
            "nullable": true
          },
          "losses": {
            "type": "integer",
            "nullable": true
          },
          "w_pct": {
            "type": "number",
            "nullable": true
          },
          "min": {
            "type": "number",
            "nullable": true,
            "description": "Average minutes as a decimal. Note this differs from `min` on NbaPlayerSeasonAverage, which is an \"MM:SS\" string; the two relations store it differently and neither is reshaped here."
          },
          "poss": {
            "type": "number",
            "nullable": true,
            "description": "Possessions."
          },
     

# --- truncated at 32 KB (817 KB total) ---
# Full source: https://artifacts.apis.io/bigballsdata-com/openapi/_original/bigballsdata-com-api-openapi.json