Getting started

Quickstart

Make your first request against the StoryStats API after your account is created.

1. Use your API key

Create a StoryStats account to get dashboard access and an API key. Enterprise teams can still book a demo to map custom coverage, throughput, and account requirements.

2. List today's games

First, discover which games are scheduled. The games endpoint returns IDs you'll use to fetch stories.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.balldontlie.io/stories/nba/games?date=2026-04-12&timezone=America/New_York"

3. Request a story

Pick a game ID from the response and fetch a story for it. Choose an audience (betting or stats) and a tone (editorial or humor).

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.balldontlie.io/stories/nba/games/18448014/pregame?audience=betting&tone=editorial"

4. Read the response

Every story exposes a tweet-length content string plus entity_tags you can use to cross-reference the BallDontLie sport APIs.

{
  "game": { "id": 18448014 },
  "story": {
    "id": 192769,
    "created_at": "2026-04-13T02:36:38.657Z",
    "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" }
      ]
    }
  }
}

5. Explore the reference

That's it. Head into the APIs to see the available endpoints, query parameters, and response schemas for the shared games and stories interface.