API Documentation

Complete reference for accessing NBA and NCAAB analytics data programmatically. Build custom integrations, mobile apps, and automated workflows with SportsFBI's powerful multi-sport REST API.

Getting Started
Authentication
Rate Limits
API Endpoints
Error Handling
Code Examples

Getting Started

Prerequisites

To use the SportsFBI API, you need:

PRO or ELITE subscription - API access requires paid subscription
API Key - Generate from your API Keys page
HTTPS support - All API requests must use HTTPS

Base URL

https://blowoutalert.sportsfbi.com/api

Quick Start

Make your first API request in under 60 seconds:

                    # Get today's NBA games
curl -X GET "https://blowoutalert.sportsfbi.com/api/nba/games/today" \
     -H "Authorization: Bearer YOUR_API_KEY"
                

Authentication

All API requests require authentication using Bearer tokens. Include your API key in the Authorization header:

Authorization: Bearer sfbi_abc123...

Getting Your API Key

Sign in to your SportsFBI account
Navigate to API Keys
Click "Generate New API Key"
Copy and securely store your key (shown only once)

⚠️ Security Best Practices

Never commit API keys to version control
Use environment variables to store keys
Rotate keys regularly (at least every 90 days)
Revoke compromised keys immediately
Use different keys for development and production

Rate Limits

API rate limits are based on your subscription tier and enforce fair usage across all users:

PRO

150/min

API key requests per minute

Full API access
Advanced stats
Matchup analysis
Up to 5 API keys

ELITE

600/min

API key requests per minute

Everything in PRO
4x higher rate limit
Player props
Priority support

Rate Limit Headers

Every API response includes rate limit information in headers:

                    RateLimit-Limit: 150
RateLimit-Remaining: 142
RateLimit-Reset: 1672531200
                

Handling Rate Limits

When you exceed your rate limit, the API returns a 429 Too Many Requests status. Implement exponential backoff:

                    // Example: Exponential backoff in JavaScript
async function fetchWithRetry(url, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url);
    if (response.status !== 429) return response;
    
    const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
    await new Promise(resolve => setTimeout(resolve, delay));
  }
  throw new Error('Max retries exceeded');
}
                

API Endpoints

All endpoints are served from: https://blowoutalert.sportsfbi.com

Free endpoints require no authentication. Pro/Elite endpoints require a valid API key with the appropriate subscription tier.

Games

GET /api/nba/games/today Free

Today's NBA games with quality ratings, team standings, and injuries.

Query Parameters

Parameter	Type	Required	Description
date	string	Optional	YYYY-MM-DD (defaults to today)
tzOffsetMin	integer	Optional	Timezone offset in minutes, −720 to 720 (e.g. −300 for EST)

GET /api/nba/games/{nbaGameId}/lineups Free

Starting lineups, bench players, injuries, and team standings for a specific game.

GET /api/nba/games/{nbaGameId}/key-suspects Free

Key Suspects analysis — players likely to exceed prop projections based on matchup, role, and usage trends.

GET /api/nba/games/{nbaGameId}/streaks Free

Streak alerts for both teams in a game — precomputed every 5 min via the feature store (10-min Redis TTL).

GET /api/nba/games/{nbaGameId}/team-trends Free

Team PPG / PAPG trends for both teams — precomputed every 5 min via the feature store (10-min Redis TTL).

GET /api/nba/plays/{nbaGameId} Free

Play-by-play data organized by quarter.

GET /api/nba/betting-odds Free

Spreads, moneylines, and totals for one or more games.

Query Parameters

Parameter	Type	Required	Description
gameIds	string	Required	Comma-separated NBA game IDs
vendor	string	Required	Sportsbook vendor name

Slate & DFS

GET /api/nba/slate/dfs-ranking Free

Precomputed DFS score ranking for today's slate. Refreshed every 5 min by cron and served from Redis (~5 ms). Falls back to on-demand computation if Redis is unavailable.

Query Parameters

Parameter	Type	Required	Description
vendor	string	Optional	`draftkings` (default) or `fanduel`

GET /api/nba/slate/streak-board Free

Players on active consecutive over-streaks. Looks at last 20 games, counts consecutive overs from most recent. Minimum streak of 2. Sorted by streak length descending.

Query Parameters

Parameter	Type	Required	Description
propType	string	Optional	`points_rebounds_assists` (default), `points`, `rebounds`, `assists`, `points_rebounds`, `points_assists`, `rebounds_assists`

Players — Free Tier

GET /api/nba/players/{playerId} Free

Player profile (name, position, height, weight, team).

GET /api/nba/players/{playerId}/seasons Free

List of seasons the player has box-score data for.

GET /api/nba/players/{playerId}/game-log Free

Game-by-game statistics for a season.

Query Parameters

Parameter	Type	Required	Description
season	integer	Required	Season start year (e.g. 2024)

GET /api/nba/players/{playerId}/stats Free

Season averages (pts, reb, ast, etc.).

Query Parameters

Parameter	Type	Required	Description
season	integer	Required	Season start year

GET /api/nba/players/{playerId}/injuries Free

Current injury status and history for a player.

GET /api/nba/players/{playerId}/vs-opponent Free

All-time stats for this player versus a specific team.

Query Parameters

Parameter	Type	Required	Description
teamAbbr	string	Required	Team abbreviation (e.g. `LAL`)

GET /api/nba/games/{nbaGameId}/player/{playerId}/box-score Free

Player box score for a specific game.

GET /api/player-injuries Free

All current player injuries across the league.

Query Parameters

Parameter	Type	Required	Description
teamId	integer	Optional	Filter by team ID
status	string	Optional	`out`, `doubtful`, `questionable`, `dtd`, `probable`

Players — Pro/Elite

GET /api/nba/players/{playerId}/advanced-stats Pro/Elite

Game-by-game advanced metrics: PIE, ORtg, DRtg, TS%, and more.

Query Parameters

Parameter	Type	Required	Description
season	integer	Required	Season start year

GET /api/nba/players/{playerId}/contracts Pro/Elite

Player contract details by season.

GET /api/nba/players/{playerId}/matchup-stats Pro/Elite

Last 5 games averaged stats with archetype detection.

GET /api/nba/players/{playerId}/role-breakdown Pro/Elite

Detailed 18-role breakdown with scores and probabilities for the player's current archetype classification.

GET /api/nba/players/{playerId}/role-analysis Pro/Elite

Condensed role analysis: primary role and top 3 role distribution — optimized for UI insights.

GET /api/nba/players/{playerId}/matchup-verdict/{opponentTeamAbbr} Auth Required

Lightweight verdict-only endpoint for icon color-coding in lineup cards. Skips full projection engine — returns favorable / neutral / unfavorable in milliseconds.

GET /api/nba/players/{playerId}/matchup-analysis/{opponentTeamAbbr} Pro/Elite

Comprehensive matchup analysis including player archetype, opponent defensive profile, usage trends, zone data, and projected score delta.

GET /api/nba/players/{playerId}/props Auth Required

Player prop betting lines for a specific game.

Query Parameters

Parameter	Type	Required	Description
game_id	string	Required	NBA API game ID

GET /api/nba/players/{playerId}/props/hit-rate Pro/Elite

Historical over/under hit rates by prop type. Precomputed and cached in Redis (1-hour TTL).

Query Parameters

Parameter	Type	Required	Description
limit	integer	Optional	Number of recent games to analyse, 1–50 (default: 25)
propType	string	Optional	Prop category filter (e.g. `points`)
line	number	Optional	Prop line value filter

GET /api/nba/players/{playerId}/clutch-stats Pro/Elite

Clutch performance — stats in close games (final margin ≤5) vs. overall season averages. Precomputed and cached in Redis (10-min TTL).

Query Parameters

Parameter	Type	Required	Description
season	integer	Required	Season start year

Leaderboards

GET /api/nba/leaderboard/{category} Free

Statistical leaderboards for live, daily, or full-season stats.

Path Parameters

Parameter	Type	Required	Description
category	string	Required	`pts`, `reb`, `ast`, `stl`, `blk`, `fg3m`, `fgm`, `fga`, `ftm`, `fta`, `plus_minus`

Query Parameters

Parameter	Type	Required	Description
mode	string	Optional	`today` (live), `daily` (completed games), `season` — default: `today`
limit	integer	Optional	Max results 1–50 (default: 10)
seasonYear	integer	Optional	Season year for `season` mode (e.g. 2024)
date	string	Optional	YYYY-MM-DD for `daily` mode
tzOffsetMin	integer	Optional	Timezone offset in minutes
onlyTodayPlayers	boolean	Optional	Season mode — restrict to players in today's games (`true`/`false`)

GET /api/nba/league-averages Free

Current league averages (pace, defensive rating, etc.).

Query Parameters

Parameter	Type	Required	Description
refresh	string	Optional	`true` to force recalculation from the database

GET /api/nba/rules Free

DFS scoring rules reference (DraftKings and FanDuel point values).

Teams

GET /api/nba/team/{teamId}/predicted-lineup Free

Predicted starting lineup based on last 15 games of player usage.

GET /api/nba/team/{teamId}/schedule Free

Team schedule with results and upcoming games.

GET /api/nba/team/{teamId}/roster Free

Full team roster with positions, jersey numbers, and contract status.

GET /api/nba/team/{teamId}/season-stats Free

Team season averages — PPG, PAPG, pace, offensive and defensive ratings.

GET /api/nba/teams/{teamAbbr}/defensive-stats Pro/Elite

Detailed defensive statistics: season averages, rim protection, paint defence, pace, and positional matchup breakdowns.

DFS Lineup Projections

POST /api/nba/lineup/projections Pro/Elite

DFS lineup projection engine — returns per-player DFS projections, lineup synergy scoring, opponent defensive profile, and role compatibility analysis for a given 2–5 player lineup.

Request Body (JSON)

Field	Type	Required	Description
playerIds	array	Required	Array of 2–5 internal player IDs
opponentTeamAbbr	string	Required	Opponent team abbreviation (e.g. `GSW`)

Games

GET /api/ncaab/games/today Free

Today's NCAAB games with team info, scores, status, and game quality ratings.

Query Parameters

Parameter	Type	Required	Description
date	string	Optional	YYYY-MM-DD (defaults to today)
tzOffsetMin	integer	Optional	Timezone offset in minutes, −720 to 720

GET /api/ncaab/games/{ncaabGameId}/lineups Free

Starting lineups, bench players, injuries, and team standings for a specific NCAAB game.

GET /api/ncaab/games/{ncaabGameId}/key-suspects Free

Key Suspects analysis for NCAAB — college players likely to exceed projections based on matchup and usage context.

GET /api/ncaab/games/{ncaabGameId}/player/{playerId}/box-score Free

Player box score for a specific NCAAB game.

GET /api/ncaab/plays/{ncaabGameId} Free

Play-by-play data organized by half.

GET /api/ncaab/betting-odds Free

Spreads, moneylines, and totals for NCAAB games.

Query Parameters

Parameter	Type	Required	Description
gameIds	string	Required	Comma-separated NCAAB game IDs
vendor	string	Required	Sportsbook vendor name

Players

GET /api/ncaab/players/{playerId} Free

Player profile (name, position, height, weight, team, jersey number).

GET /api/ncaab/players/{playerId}/seasons Free

List of seasons the player has box-score data for.

GET /api/ncaab/players/{playerId}/game-log Free

Game-by-game statistics for a NCAAB season.

Query Parameters

Parameter	Type	Required	Description
season	integer	Required	Season start year (e.g. 2024)

GET /api/ncaab/players/{playerId}/stats Free

Season averages for a NCAAB player.

Query Parameters

Parameter	Type	Required	Description
season	integer	Required	Season start year

GET /api/ncaab/players/{playerId}/matchup-analysis/{opponentTeamAbbr} Free

Matchup breakdown for a NCAAB player vs a specific opponent — usage context, defensive profile, and projected impact.

Leaderboards

GET /api/ncaab/leaderboard/{category} Free

Statistical leaderboards for NCAAB — live, daily, or season modes.

Path Parameters

Parameter	Type	Required	Description
category	string	Required	`pts`, `reb`, `ast`, `stl`, `blk`, `fg3m`, `fgm`, `fga`, `ftm`, `fta`, `plus_minus`

Query Parameters

Parameter	Type	Required	Description
mode	string	Optional	`today`, `daily`, or `season` (default: `today`)
limit	integer	Optional	Max results 1–50 (default: 10)
seasonYear	integer	Optional	Season year for `season` mode
date	string	Optional	YYYY-MM-DD for `daily` mode
tzOffsetMin	integer	Optional	Timezone offset in minutes

Teams

GET /api/ncaab/team/{teamId}/schedule Free

NCAAB team schedule with results and upcoming games.

GET /api/ncaab/team/{teamId}/roster Free

Full team roster with player positions and jersey numbers.

GET /api/ncaab/team/{teamId}/stats Free

Team statistics including PPG, PAPG, pace, and offensive / defensive breakdowns.

GET /api/ncaab/team/{teamId}/season-stats Free

Team season averages across all games played.

System & Utilities

GET /api/health Free

System health check. Reports database connectivity, Redis status, and feature store pipeline freshness (gameFeatures and playerFeatures staleness flags).

GET /rate-limit-status Free

Your current rate-limit usage and remaining quota for the active window.

GET /auth/status Free

Current authentication status — tier, subscription state, and API key validity.

Error Handling

The API uses standard HTTP status codes and returns errors in JSON format:

HTTP Status Codes

Status Code	Meaning	Description
200	OK	Request successful
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient subscription tier
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Response Format

                    {
  "error": "Invalid API key",
  "statusCode": 401,
  "timestamp": "2026-02-09T12:34:56.789Z"
}
                

Code Examples

JavaScript (Node.js)

                    const fetch = require('node-fetch');

const API_KEY = process.env.SPORTSFBI_API_KEY;
const BASE_URL = 'https://blowoutalert.sportsfbi.com/api';

async function getTodayGames() {
  const response = await fetch(`${BASE_URL}/nba/games/today`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return await response.json();
}

getTodayGames()
  .then(games => console.log(games))
  .catch(err => console.error(err));
                

Python

                    import requests
import os

API_KEY = os.environ['SPORTSFBI_API_KEY']
BASE_URL = 'https://blowoutalert.sportsfbi.com/api'

def get_today_games():
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }
    
    response = requests.get(
        f'{BASE_URL}/nba/games/today',
        headers=headers
    )
    
    response.raise_for_status()
    return response.json()

try:
    games = get_today_games()
    print(games)
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')
                

cURL

                    # Get today's games
curl -X GET "https://blowoutalert.sportsfbi.com/api/nba/games/today" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Get player profile
curl -X GET "https://blowoutalert.sportsfbi.com/api/nba/players/123" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Get leaderboard
curl -X GET "https://blowoutalert.sportsfbi.com/api/nba/leaderboard/pts?mode=today&limit=10" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Get matchup analysis (Pro/Elite)
curl -X GET "https://blowoutalert.sportsfbi.com/api/nba/players/123/matchup-analysis/LAL" \
     -H "Authorization: Bearer YOUR_API_KEY"
                

Response Example

                    {
  "success": true,
  "data": [
    {
      "id": 1234,
      "nbaGameId": "0022600789",
      "status": "live",
      "homeTeam": {
        "id": 5,
        "name": "Lakers",
        "abbreviation": "LAL",
        "score": 98
      },
      "awayTeam": {
        "id": 10,
        "name": "Warriors",
        "abbreviation": "GSW",
        "score": 95
      },
      "period": 3,
      "gameClock": "5:23",
      "startTime": "2026-02-09T19:30:00Z"
    }
  ]
}
                

Support & Resources

Need help with the API? We're here to assist:

API Keys: Manage your API keys
Profile: View subscription and rate limits
Upgrade: Increase your rate limits
Issues: Check the GitHub Issues

📧 Contact Support

For API-specific questions or issues, please contact our support team with your API key ID (not the full key) and a description of your issue.