API example
NBA endpoints
All NBA endpoints live under https://api.balldontlie.io/stories/nba. Every request requires a Bearer API key in the Authorization header.
List games
Returns all NBA games scheduled on a given date. Use this endpoint first to discover game IDs, then pass those IDs to the story endpoints below.
/stories/nba/gamesQuery parameters
| Name | Type | Required | Description |
|---|---|---|---|
| date | string | Yes | ISO-8601 calendar date in YYYY-MM-DD format (e.g. 2026-04-12). |
| timezone | string | No | IANA timezone name used to resolve the date boundary. Defaults to UTC. |
Example request
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.balldontlie.io/stories/nba/games?date=2026-04-12&timezone=America/New_York"Example response
{
"data": [
{
"id": 18448014,
"home_team": {
"id": 21,
"conference": "West",
"division": "Northwest",
"city": "Oklahoma City",
"name": "Thunder",
"full_name": "Oklahoma City Thunder",
"abbreviation": "OKC"
},
"away_team": {
"id": 24,
"conference": "West",
"division": "Pacific",
"city": "Phoenix",
"name": "Suns",
"full_name": "Phoenix Suns",
"abbreviation": "PHX"
},
"start_time": "2026-04-12T23:00:00.000-04:00"
}
]
}Response schema
data
Games scheduled on the requested date, ordered by start_time ascending.
| Field | Type | Description |
|---|---|---|
| id | integer | Game identifier. Pass this value as :game_id to the story endpoints below. |
| home_team | object | Home team. See Team below. |
| away_team | object | Away team. See Team below. |
| start_time | string (date-time) | Scheduled tipoff in RFC 3339 format. The UTC offset reflects the timezone query parameter (UTC when omitted). |
Team
Returned on both home_team and away_team for every NBA game.
| Field | Type | Description |
|---|---|---|
| id | integer | Stable BallDontLie team identifier. Joins to the NBA teams endpoint. |
| abbreviation | string | Three-letter team code (e.g. OKC). |
| full_name | string | Full display name (e.g. Oklahoma City Thunder). |
| name | string | Team nickname (e.g. Thunder). |
| city | string | Home city (e.g. Oklahoma City). |
| conference | string | One of East or West. |
| division | string | Division name (e.g. Pacific, Northwest). |
Get pregame story
Returns a single aggregated pregame story. Generated within 1 hour before the scheduled start time. Returns 404 if the story has not been generated yet (game is more than 1 hour away).
/stories/nba/games/{game_id}/pregameQuery parameters
| Name | Type | Required | Description |
|---|---|---|---|
| audience | string | No | Either betting or stats. Defaults to betting. |
| tone | string | No | Either editorial or humor. Defaults to editorial. |
Example request
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.balldontlie.io/stories/nba/games/18448014/pregame?audience=betting&tone=editorial"Example response
{
"game": { "id": 18448014 },
"story": {
"id": 192276,
"created_at": "2026-04-12T23:35:38.422Z",
"content": "OKC-PHX has been hammered by absences and the market has moved with it: the line climbed from OKC -5.5 to -7.5, but the total still sits at 213.5 even as projections land at 229.9. Booker, Green, Allen and Shai Gilgeous-Alexander are all out.",
"entity_tags": {
"teams": [
{ "id": 21, "name": "Oklahoma City Thunder", "abbreviation": "OKC" },
{ "id": 24, "name": "Phoenix Suns", "abbreviation": "PHX" }
],
"players": [
{ "id": 175, "name": "Shai Gilgeous-Alexander", "team": "OKC" },
{ "id": 57, "name": "Devin Booker" },
{ "id": 17895966, "name": "Jalen Green" },
{ "id": 8, "name": "Grayson Allen", "team": "PHX" }
]
}
}
}Response schema
game
Compact reference to the game this response is scoped to. Echoes the :game_id path parameter.
| Field | Type | Description |
|---|---|---|
| id | integer | Game identifier matching the one supplied in the request path. |
story
The single narrative object for this phase. Deterministic for a given (game_id, audience, tone) tuple.
| Field | Type | Description |
|---|---|---|
| id | integer | Stable story identifier. Safe to use as an idempotency key. |
| created_at | string (date-time) | RFC 3339 timestamp (UTC) marking when the narrative was written. |
| content | string| null | Tweet-length narrative body (≤280 characters). Null only in the rare case that the requested tone has not yet been rendered for this story. |
| entity_tags | object | Teams and players referenced in content. See entity_tags below. |
entity_tags
Structured list of the teams and players referenced in the narrative. Use the IDs to join to the corresponding BallDontLie sport APIs.
| Field | Type | Description |
|---|---|---|
| teams | array<object> | Teams mentioned in the story. Each element is { id: integer, name: string, abbreviation: string }. |
| players | array<object> | Players mentioned in the story. Each element is { id: integer, name: string, team?: string }, where team is the abbreviation when known. |
Get live stories
Returns event-driven stories for a live game, sorted oldest to newest by created_at. Live games produce guaranteed period-end checkpoints plus conditional stories triggered by momentum shifts, prop breaches, and milestones. Returns an empty array if no live stories have been generated yet.
/stories/nba/games/{game_id}/liveQuery parameters
| Name | Type | Required | Description |
|---|---|---|---|
| audience | string | No | Either betting or stats. Defaults to betting. |
| tone | string | No | Either editorial or humor. Defaults to editorial. |
Example request
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.balldontlie.io/stories/nba/games/18448014/live?audience=betting&tone=editorial"Example response
{
"game": { "id": 18448014 },
"data": [
{
"id": 192769,
"created_at": "2026-04-13T02:36:38.657Z",
"type": "game_over",
"content": "PHX 135, OKC 103: Jamaree Bouyea posted 27 pts, 5 reb, 9 ast in 40 min, and the 238 total cleared 213.5 while the Suns covered +7.5.",
"entity_tags": {
"teams": [
{ "id": 21, "name": "Oklahoma City Thunder", "abbreviation": "OKC" },
{ "id": 24, "name": "Phoenix Suns", "abbreviation": "PHX" }
],
"players": [
{ "id": 44477062, "name": "Jamaree Bouyea" },
{ "id": 1028218679, "name": "Branden Carlson", "team": "OKC" }
]
},
"game_snapshot": {
"period": 4,
"home_score": 103,
"away_score": 135,
"minutes_remaining": 0
}
}
]
}Response schema
game
Compact reference to the game this response is scoped to. Echoes the :game_id path parameter.
| Field | Type | Description |
|---|---|---|
| id | integer | Game identifier matching the one supplied in the request path. |
data
Array of live stories for the game, ordered oldest to newest by created_at. Empty if no live stories have fired yet.
| Field | Type | Description |
|---|---|---|
| id | integer | Stable story identifier. Safe to use as an idempotency key. |
| created_at | string (date-time) | RFC 3339 timestamp (UTC) marking when the narrative was written. |
| type | string | Detection module that produced this story (e.g. game_over, close_game, prop_exceeded, batter_breakout). Useful for routing stories into downstream product surfaces. |
| content | string| null | Tweet-length narrative body (≤280 characters). Null only in the rare case that the requested tone has not yet been rendered for this story. |
| entity_tags | object | Teams and players referenced in content. See entity_tags below. |
| game_snapshot | object | Score and clock at the moment the story fired. See game_snapshot below. |
entity_tags
Structured list of the teams and players referenced in the narrative. Use the IDs to join to the corresponding BallDontLie sport APIs.
| Field | Type | Description |
|---|---|---|
| teams | array<object> | Teams mentioned in the story. Each element is { id: integer, name: string, abbreviation: string }. |
| players | array<object> | Players mentioned in the story. Each element is { id: integer, name: string, team?: string }, where team is the abbreviation when known. |
game_snapshot
Point-in-time state of the game when the story was generated. Useful for rendering a score banner alongside the narrative.
| Field | Type | Description |
|---|---|---|
| home_score | integer | Home team score at the moment the story fired. |
| away_score | integer | Away team score at the moment the story fired. |
| period | integer | Quarter number. 1–4 for regulation, 5+ for overtime periods. |
| minutes_remaining | integer | Whole minutes remaining in the current period. |
| clock | string| null | Raw game-clock string when available (e.g. "6:22"). Present on most live triggers; may be absent on period-boundary events. |
Get postgame story
Returns the most recent postgame story, generated immediately after the game goes final. Evaluates the pregame narrative against actual results. Returns 404 if no postgame story has been generated yet.
/stories/nba/games/{game_id}/postgameQuery parameters
| Name | Type | Required | Description |
|---|---|---|---|
| audience | string | No | Either betting or stats. Defaults to betting. |
| tone | string | No | Either editorial or humor. Defaults to editorial. |
Example request
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.balldontlie.io/stories/nba/games/18448014/postgame?audience=betting&tone=editorial"Example response
{
"game": { "id": 18448014 },
"story": {
"id": 192772,
"created_at": "2026-04-13T02:40:12.118Z",
"content": "PHX turned OKC -7.5 into a rout, ripping a 65-47 run from Q1 into Q2 and cruising to a 135-103 win. Ryan Dunn scored 20, Branden Carlson had 26 for OKC, and Aaron Wiggins finished with 3 on a 17.5-pt line as the Thunder were buried.",
"entity_tags": {
"teams": [
{ "id": 21, "name": "Oklahoma City Thunder", "abbreviation": "OKC" },
{ "id": 24, "name": "Phoenix Suns", "abbreviation": "PHX" }
],
"players": [
{ "id": 1028025723, "name": "Ryan Dunn" },
{ "id": 1028218679, "name": "Branden Carlson", "team": "OKC" },
{ "id": 17896078, "name": "Aaron Wiggins", "team": "OKC" }
]
}
}
}Response schema
game
Compact reference to the game this response is scoped to. Echoes the :game_id path parameter.
| Field | Type | Description |
|---|---|---|
| id | integer | Game identifier matching the one supplied in the request path. |
story
The single narrative object for this phase. Deterministic for a given (game_id, audience, tone) tuple.
| Field | Type | Description |
|---|---|---|
| id | integer | Stable story identifier. Safe to use as an idempotency key. |
| created_at | string (date-time) | RFC 3339 timestamp (UTC) marking when the narrative was written. |
| content | string| null | Tweet-length narrative body (≤280 characters). Null only in the rare case that the requested tone has not yet been rendered for this story. |
| entity_tags | object | Teams and players referenced in content. See entity_tags below. |
entity_tags
Structured list of the teams and players referenced in the narrative. Use the IDs to join to the corresponding BallDontLie sport APIs.
| Field | Type | Description |
|---|---|---|
| teams | array<object> | Teams mentioned in the story. Each element is { id: integer, name: string, abbreviation: string }. |
| players | array<object> | Players mentioned in the story. Each element is { id: integer, name: string, team?: string }, where team is the abbreviation when known. |