Build for the game.

Getting started

The fastest way to try the API is a personal token: a token you make for yourself, for your own scripts. Tools other managers will use need an application and OAuth instead — see Authentication.

1. Make a personal token

In the game, open Settings → API & third-party apps → Personal tokens → New token. Give it a name, tick the scopes you need (start with Public and Team), choose how long it lasts, and create it. The token (it starts with bbpat_) is shown once: copy it somewhere safe. Anyone who has it can read your club as you, until it expires or you revoke it.

2. Call the API

curl -s https://sb1-api.buzzerbeater.com/v1/me \
  -H "Authorization: Bearer $BB_TOKEN"

{
  "id": "0192a4b0-…",
  "username": "coach_marco",
  "isSupporter": true,
  "teams": [
    { "id": "0192a4c1-…", "name": "Venezia Lagunari", "shortName": "VEN", "kind": "ManagedTeam" }
  ],
  "scopes": ["Public", "Team"]
}

Then read your roster, with skills since the token has the Team scope:

curl -s https://sb1-api.buzzerbeater.com/v1/teams/$TEAM_ID/roster \
  -H "Authorization: Bearer $BB_TOKEN"

3. Python

import os, requests

API = "https://sb1-api.buzzerbeater.com/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['BB_TOKEN']}"

me = session.get(f"{API}/me").json()
club = next(team for team in me["teams"] if team["kind"] == "ManagedTeam")

history = session.get(f"{API}/teams/{club['id']}/training/history", params={"limit": 10}).json()
for week in history["sessions"]:
    print(week["trainedAt"], week["type"], week["efficiencyPercent"], week["conditions"])

4. JavaScript (Node 18+)

const API = "https://sb1-api.buzzerbeater.com/v1";
const headers = { Authorization: `Bearer ${process.env.BB_TOKEN}` };

const me = await fetch(`${API}/me`, { headers }).then((r) => r.json());
const club = me.teams.find((team) => team.kind === "ManagedTeam");
const roster = await fetch(`${API}/teams/${club.id}/roster`, { headers }).then((r) => r.json());
console.table(roster.players.map((p) => ({ name: `${p.firstName} ${p.lastName}`, age: p.age, dmi: p.dmi })));

Good habits

• Cache what does not change often (seasons, countries, a finished match's box score) instead of asking again. Each call counts against the manager's daily quota — see Quotas.
• Read the X-RateLimit-Remaining header and slow down before you hit zero.
• Never put a token in a URL, a web page, a public repository or a screenshot. If one leaks, revoke it in the game at once.
• Browsers cannot call the API directly from another site (there is no CORS for third-party origins). A web tool calls it from its own server, which is also where its tokens belong.

The response shapes shown in the guides are abbreviated; the complete, always-current schema of every response is in the interactive reference.