Getting started

Three calls: one to make a key, one to use it, one to page.

1. Create a key

Keys belong to a Bandwagon account. Sign in to the app (or the web app) and create one from Settings → Developer, or call the account API with your app session:

curl -X POST https://bandwagon.fyi/v1/me/api-keys \
  -H "Authorization: Bearer <your app session token>" \
  -H "content-type: application/json" \
  -d '{"name":"my first key"}'

{ "key": "bwk_…", "id": "…", "name": "my first key", "prefix": "bwk_abc1234", "tier": "free", … }

The key is shown once. Store it; we keep only a hash. You can hold up to 5 active keys and revoke any of them (DELETE /v1/me/api-keys/:id).

2. Make a call

curl https://bandwagon.fyi/data/v1/teams?league=epl \
  -H "Authorization: Bearer bwk_…"

{
  "data": [ { "slug": "arsenal", "name": "Arsenal", "tag": "ARSENAL", "league": { "id": "epl", … }, "sources": { "wikidata_id": "Q9617", "espn_id": "359" }, … } ],
  "meta": { "generated_at": "2026-10-28T14:02:11.000Z", "tier": "free", "next_cursor": null }
}

3. Page

List endpoints take limit (1–200, default 50) and return meta.next_cursor. Pass it back as cursor until it is null. Cursors are opaque; do not build them.

curl "https://bandwagon.fyi/data/v1/games?league=nfl&from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z&cursor=eyJzIjoi…" \
  -H "Authorization: Bearer bwk_…"

Caching

Responses carry an ETag and Cache-Control: private, max-age. Send If-None-Match and a 304 costs you nothing new to parse (it still counts as a request).

Freshness

Sentiment endpoints return meta.as_of: the newest day your tier may see. Free keys get completed days with a one-day lag; pro keys get today's running day, recomputed hourly by our workers. The Index is weekly for everyone, published once the Monday–Sunday week is complete.

Identifiers

• Slugs name teams and people in URLs: kansas-city-chiefs, patrick-mahomes. They are stable.
• $tags are what sentiment is keyed by: CHIEFS, MAHOMES. Teams always have one; a person has one only when the app does. Sentiment endpoints accept either.
• Seasons are named by their starting year: 2026 for NFL 2026 and for the 2026–27 Premier League.

Errors