Versioning

/v1/ is the permanent namespace. A breaking change never ships as a second URL tree. It ships as a dated version inside /v1/, pinned per API key, so a key that works today keeps receiving the shape it was built against until you choose to move.

How a version is chosen

In order, highest first:

The Bbs-Version request header, for that one request.
The version your API key is pinned to. A key issued today is pinned to the current version; a key issued earlier stays on the version it was issued against. Rotating a key keeps its pin, so regenerating a key never changes the shape you receive.
If there is no key and no header (the public GET /v1/sports and GET /v1/coverage catalogue routes), the oldest supported version.

httphttp

GET /v1/athletes/123 HTTP/1.1
Host: api.bigballsdata.com
Authorization: Bearer <your key>
Bbs-Version: 2026-09-01

Because the pin lives on the key, you can hold a second key on a newer version to test against, with no header handling in your code.

What you get back

Every response, errors included, carries a Bbs-Version header naming the version that answered it. If a body does not look the way you expect, that header says which contract produced it. It is readable from browser clients.

httphttp

HTTP/1.1 200 OK
Bbs-Version: 2026-11-09

An unrecognised Bbs-Version is rejected with a 400 that lists every supported version. It is never silently served as a different version.

Scope

Versioning applies to JSON responses from the REST API. WebSocket messages and non-JSON bodies are not versioned.
A version changes the shape of a response, not the URL. There is no /v2/ for a different response shape; that prefix is reserved for a different resource model.
Additive changes (a new field, a new endpoint) do not get a new version. A field you do not recognise is safe to ignore.

Versions

Version	Status	What changed
2026-11-09	Current. New keys are pinned here.	Athlete cross-reference ids and NCAAF season team ids now use source-neutral attribute names. On `/v1/athletes` and `/v1/athletes/{id}`, `external_ids` carries `encyclopedia` and `record_book`. On `/v1/players/{id}/stats`, `seasons[].team` carries `external_team_id`. Every id value is unchanged, so an existing join keeps working; only the attribute name moved. Keys pinned to `2026-09-01` keep receiving the previous spelling.
2026-09-01	Supported. The launch shape, and the default for unauthenticated routes.	The original shape. Keys issued before 2026-11-09 are pinned here.

Moving to a newer version

Send Bbs-Version: 2026-11-09 on a request to see the newer shape without changing anything on your account, compare it against what you receive today, then update your code. Nothing is switched for you.

Retired routes

Separately from versions, a route can be retired. A deprecated route answers with Deprecation, Sunset and a Link header whose successor-version relation names its replacement. After its sunset date it answers 410 Gone with the successor in the body, rather than a 404, so the fix is a URL change. The legacy /v1/nerd/* aliases sunset on 2026-09-01 and now return 410; each names its replacement.