Skip to content
DunkAPI

NBA API documentation

24 basketball data endpoints over REST and MCP. One key, credits per call.

Coming from stats.nba.com or nba_api? See how they compare.

Your first call

Sign up for a free key (500 credits every month, no card), swap it in for YOUR_API_KEY, and send this. get_standings costs 2 credits.

Request

curl -X POST https://mcp.dunkapi.com/v1/get_standings \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "season": 2026
}'

Response

json
{
  "season": 2026,
  "standings": [
    {
      "team_id": "25",
      "abbrev": "OKC",
      "display_name": "Oklahoma City Thunder",
      "conference": "Western",
      "wins": 64,
      "losses": 18,
      "conf_wins": 41,
      "conf_losses": 11,
      "home_wins": 34,
      "home_losses": 8,
  ...

First 14 lines. Full response and every field

REST / cURL

POST to /v1/{tool_name} with your params as JSON body. No MCP client needed:

bash
curl -X POST https://mcp.dunkapi.com/v1/list_teams \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

With parameters:

bash
curl -X POST https://mcp.dunkapi.com/v1/get_standings \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"season":2026}'

Save the raw JSON

Keep your key in an environment variable so it never sits in a script or a chat, and write each response to a file:

bash
export DUNKAPI_API_KEY="your key here"

curl -s -X POST https://mcp.dunkapi.com/v1/get_standings \
  -H "Content-Type: application/json" \
  -H "x-api-key: $DUNKAPI_API_KEY" \
  -d '{"season":2026}' \
  -o get_standings.json

The file holds exactly what the API returned. Tools that page their results return a next_offset; send it back as offset for the next page.

ChatGPT and Claude

Both connect to the MCP server with a sign-in instead of a key: you sign in to DunkAPI once and press Allow. Step-by-step for ChatGPT and Claude.

Python

The official client is on PyPI. It has no required dependencies. Set DUNKAPI_API_KEY to your key and it is picked up automatically:

bash
pip install dunkapi

Then call any endpoint as a method (the example uses pandas, pip install "dunkapi[pandas]"):

python
from dunkapi import Client, to_dataframe

client = Client()

props = client.get_player_props(
    game_id="401810726",
    market="player_points",
    bookmaker="draftkings",
)
df = to_dataframe(props, key="props")
print(df[["player_name", "line", "over_odds", "under_odds"]].head(10))

Claude Desktop

Add to your claude_desktop_config.json:

json
{
  "mcpServers": {
    "dunkapi": {
      "url": "https://mcp.dunkapi.com/mcp?key=YOUR_API_KEY"
    }
  }
}

Claude Code

One command:

bash
claude mcp add dunkapi https://mcp.dunkapi.com/mcp?key=YOUR_API_KEY --transport streamable-http

Find the right call

All 24 questions

What timestamps mean, whether lines are pre-game, and what you can do with the data: data timing and rights.

Working Python, JavaScript and cURL for common questions, each run against the live API.

Endpoints

24 endpoints by category. Each page has parameters, requests in three formats, a full example response and every response field.

Reference

Authentication

Every request requires an API key. Pass it via header or query parameter:

bash
x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
# or (MCP only)
?key=YOUR_API_KEY

Verify your email, then create an API key from the dashboard. Free accounts get 500 credits every month.

Base URL

text
https://mcp.dunkapi.com

REST API: POST /v1/{tool} with JSON body. Works with cURL, Python, any HTTP client.

MCP: POST /mcp via Streamable HTTP. Works with Claude Desktop, Claude Code, Cursor, and any MCP client.

Rate limits

Credit balanceRate limit
100 credits or more60 req/min
Under 100 credits10 req/min

The limit is the same on every plan. It is burst protection, not the spend boundary; credits are that, and they are enforced per request. Running low slows you down so you notice before the balance reaches zero.

Error handling

CodeMeaningWhat to do
400Invalid parametersCheck required fields and value types
401Invalid or missing API keyCheck your x-api-key header
402Insufficient creditsTop up your wallet or upgrade your plan
429Rate limit exceededWait and retry (see limits above)
500Server errorRetry with idempotency key. Credits auto-refund on server errors.

Pass x-idempotency-key or x-request-id headers to make retries duplicate-safe.

Data coverage

Women's National Basketball Association (WNBA)

DunkAPI also serves the WNBA. Pass "league": "wnba" to any tool that lists it, or connect to https://mcp.dunkapi.com/mcp/wnba. WNBA API coverage.

NCAA Division I men's basketball (NCAAM)

DunkAPI also serves the NCAAM. Pass "league": "ncaam" to any tool that lists it, or connect to https://mcp.dunkapi.com/mcp/ncaam. NCAAM API coverage.

NCAA Division I women's basketball (NCAAW)

DunkAPI also serves the NCAAW. Pass "league": "ncaaw" to any tool that lists it, or connect to https://mcp.dunkapi.com/mcp/ncaaw. NCAAW API coverage.

National Basketball League (Australia and New Zealand) (NBL)

DunkAPI also serves the NBL. Pass "league": "nbl" to any tool that lists it, or connect to https://mcp.dunkapi.com/mcp/nbl. NBL API coverage.

DataStatusCoverageVolume
Games and box scores
Scores, both teams' box scores and every player's line: minutes, points, shooting, rebounds, assists, steals, blocks, turnovers, fouls, plus-minus.
About one game in eight from 2012-13 to 2017-18 has no box score in the source; those lines are counted from the play-by-play (97-100% exact where checked), without minutes or plus-minus. 26 games have a box score but no play-by-play.
Partial2003-04 to currentEvery game, every player
Play-by-play
Every play with clock, score, players involved, shot type and points.
Available2003-04 to currentAbout 450 plays per NBA game
Shot locations
Each shot's x/y in feet, distance, zone and our expected points.
Available2003-04 to currentEvery field goal attempt
Win probability
The home team's win probability after each play, as computed upstream, not by us.
From 2017-18 only.
Partial2018 to currentAfter every play
Odds
Moneyline, spread and total by sportsbook; opening and closing lines from July 2020 (sportsbook odds archive), the final pregame line only in the earlier seasons.
No lines before 2012-13; opening and closing lines from July 2020; player props are separate (get_player_props, from May 2023).
Partial2013-14 to current4 to 12 books per regular-season game to 2023-24; 6 to 8 with opening and closing lines since July 2020
Ratings
Our Elo, before and after every game.
Available2003-04 to currentEvery team, every game
Injury report
Each listed player's status, injury and expected return, captured daily (NBA and WNBA).
Daily captures from launch; no history before that.
PartialFrom launchDaily

Coverage describes the datasets DunkAPI supports. Freshness and operational health are tracked separately.

Odds snapshot definitions

opening: The first line a sportsbook posted for the game, held from 2023-24 and, from July 2020, in the sportsbook odds archive.

closing: The sportsbook's last line before tip-off.

Odds coverage currently documents the books reported with each game: 4 to 12 per regular-season NBA game from 2013-14 to 2023-24, 10 to 12 from 2020-21 (DraftKings, Caesars, BetMGM, Unibet and Betfair among them in 2023-24), plus up to eight books with opening and closing lines since July 2020, among them DraftKings, FanDuel, BetMGM, ESPN BET and Pinnacle. No lines before 2012-13, and the daily feed is one or two books a game since 2024-25; the other books come from the sportsbook odds archive. Before 2023-24 we hold each sportsbook's final pregame line, stored as the close, for 4 to 12 books per regular-season NBA game from 2013-14 (10 to 12 from 2020-21). Opening and closing lines in that daily feed start in 2023-24, usually from one book from 2024-25. Since July 2020 the sportsbook odds archive adds opening and closing lines per book for nearly every game, a median of 7 books in 2020-21 to 2022-23 and 8 since 2023-24. Daily snapshots before each game from launch.

Response format

REST API

All successful REST responses wrap the result in a data key:

json
{ "data": { "teams": [...], "count": 32 } }

Error responses return:

json
{ "error": "Insufficient credits", "message": "This tool costs 5 credits, you have 2" }

MCP Protocol

MCP responses follow the standard MCP tool result format. The data is returned directly (no data wrapper). Both access methods return identical data, just different envelopes.

Conventions

Seasons: the year the season ends (2025 = 2024-25); WNBA: the calendar year. Example: 2025.

Game IDs: a game id, e.g. 401705127 (a game id; find them with list_games). Get them from list_games or get_schedule.

Team abbreviations: Standard codes (BOS, LAL, NY (or a team id); list_teams has them). Use list_teams if unsure.

Pagination: Endpoints use a limit parameter. No cursor or offset. Narrow your filters to get different slices of data.

Credits: Deducted before the request executes. Automatically refunded on server errors. Monthly credits are used first, then wallet balance.

Ready to start?

500 free credits every month. No credit card required.

Get a free key