Changelog

How versioning works

Every response carries meta.version. The version bumps only for breaking changes: removing or renaming a field, changing a status-code contract, or altering the envelope shape. Additive changes (new endpoints, new fields, new error codes) ship without a version bump and are listed here as additive.

Two documented exceptions shipped under v1 without a bump: the 2026-07-24 pre-GA analysis-surface change, and the 2026-09-11 quota hard-stop (at-cap metered routes now return 429 QUOTA_EXCEEDED). Both are called out in their dated entries below.

v1: current

2026-09-11 · breaking (quota policy)

Paid self-serve tiers (Hobby–Growth) now hard-stop every metered route at included units: further requests return 429 with error.code: "QUOTA_EXCEEDED" until the period resets or you upgrade. Standard endpoints no longer continue past the cap. Free is unchanged (already a hard stop). Enterprise cap handling stays contract-defined. There is no metered overage billing.

Clients that assumed paid standard routes would keep returning 200 after the allowance is exhausted must handle QUOTA_EXCEEDED (see Quotas and Errors).

2026-09-11 · additive (odds)

• Odds boards and paged history. Discovery GET /v1/contests/{id}/odds/markets stays 1×. Spot boards (GET /v1/contests/{id}/odds, GET /v1/persons/{id}/odds) are 5×. History (GET /v1/contests/{id}/odds/history, GET /v1/persons/{id}/odds/history) is 10× per page. Paging fields are on data (truncated, next_cursor, next_before); prefer cursor=data.next_cursor. Odds stay Free-accessible. Full contract: Quotas · Odds history pages.

2026-08-29 · additive

• Injury availability and history. One new endpoint, GET /v1/persons/{id}/injuries, returns per-source injury history with derived injured-list intervals. Person detail, team roster entries, and the player-prop analysis card each gain an optional injury object, and the prop card also gains injury_window_flags (annotation only: averages and hit rates are unchanged). Healthy players serialize exactly as before, the field is omitted rather than null. Coverage is MLB (two sources, history back to 2024-01-01) plus current status for NFL, NBA, NHL, and WNBA from the ESPN report; every lane refreshes hourly. New schemas: PersonDetailView, PersonInjuryHistory, SourceInjuryHistory, InjuryStatusView, InjuryEventView, DerivedInterval, and InjuryWindowFlags. See Injuries for coverage and the rules for reading it.
  Generated-client note: the JSON wire is additive, but the OpenAPI component for the person-detail response was renamed from ApiResponsePerson to ApiResponsePersonDetail. If you generate a typed client from the spec, regenerate it and update any import of the old model name; the runtime response shape is unchanged.

2026-08-14 · additive

• NFL kicking + punting stats: two new football phases across boxscores, game logs, season aggregates, and prop analysis: kicking (fga, fgm, xpa, xpm, fg_long, kicking_points, derived fg_pct/xp_pct) and punting (punts, punt_yards, punt_touchbacks, punt_inside_20, punt_long, derived punt_avg). Both NFL seasons are fully populated. fg_long/punt_long aggregate as max (season and every analysis window), never as a sum or mean.
• external_ids on persons: person detail and search responses carry an optional external_ids map of allowlisted provider ids ({"espn": ["4362628"]}; plural because a merged person can legitimately hold several). Absent, never empty, when no allowlisted id exists. ESPN is the first allowlisted source.
• Contest stage surfaced + filterable: game and contest summaries carry stage (preseason / regular / postseason / exhibition / allstar), and edition /games and /contests accept an exact ?stage= filter. Omitting the filter returns all stages (unchanged behavior). Preseason games remain excluded from season stat aggregates by design.

2026-08-10 · additive

• NFL play-by-play: GET /v1/contests/{contest_id}/play-by-play now serves football contests: a flat drives array in game order with each drive's ordered plays (down/distance/yards-to-endzone, running score, typed play_type vocabulary), during a live game the in-flight drive rides the same array, and a win-probability series at the standard/full detail tiers. Baseball contests keep the identical Statcast shape they always had: the response is shaped by the contest's sport, and cross-sport query params are rejected. Coverage: 2024 + 2025 NFL seasons and the live 2026 season.
• New sports and competitions: golf (PGA/LPGA per-round scoring), racing (F1/NASCAR/IndyCar results + drivers'/constructors' standings tables), tennis (ATP/WTA), MMA (UFC), Australian rules (AFL), rugby league (NRL), lacrosse (PLL), and four soccer competitions (NWSL, Leagues Cup, Copa Libertadores, Copa Sudamericana), each with contests, results, and per-player stat phases where the source serves them.
• Standings tables: /standings/{table} serves registry-driven tables per competition (league, and for racing drivers/constructors); available tables are advertised on /capabilities.

2026-07-24 · breaking

The /v1/analysis surface dropped its duplicate legacy projections in favor of the windowed shapes that superseded them. Migration is mechanical:

Also breaking: a prop card / board entry with nothing to say now omits context entirely (previously always-null), and pitching-stat board rows no longer carry the batter-facing pitcher.

2026-07-24 · additive

• GET /v1/persons/{person_id}/overview: the composed player overview: profile, current team, per-season stat capabilities, materialized season stats, and the most recent 30 context-rich game-log entries in one CDN-cacheable read (season optional, defaults to the player's latest season with data).
• Sport-tagged analysis context on prop cards and stat-board entries, produced by a per-(sport, phase, market) provider registry: baseball batting props carry platoon splits by opposing starter hand; basketball/hockey props carry back-to-back vs rested splits; baseball batting board rows carry the opposing probable starter. Absent when no provider fires: the schema never advertises context the API cannot serve.
• Self-correcting UNKNOWN_STAT errors: the 400 now carries machine-readable valid_stats (every phase-qualified measure id for the resolved sport, or all sports when no competition was supplied), aliases, and a capabilities discovery pointer.
• Prop cards and stat boards now exclude not-yet-played games from logs, averages, and hit rates (scheduled games previously polluted them as zero-stat entries), and a play-by-play player filter matching zero plate appearances returns 200 with an empty list instead of 404.

2026-07 · additive

• Added NBA Summer League (Las Vegas) as the nba_summer_league competition. Reuses the basketball schema (box scores, season stats, player search) and shares the NBA franchises, so a player's Summer League and regular-season lines resolve to the same person and team. Query it like any competition, e.g. ?competition=nba_summer_league.
• Added /v1/analysis/stat-board (10× weight, paid tier): slate-wide over-rate board for a competition + date + stat, with recommended and full_slate rankings.
• Added /v1/analysis/compare-teams (10× weight, paid tier): a head-to-head comparison card for two teams within a competition edition.

2026-05-15 · additive

• Added /v1/analysis/player-prop (10× weight, paid tier).
• Added meta.cache: "HIT" | "MISS" | "STALE" to every envelope.
• New error code: NOT_SUPPORTED (501) for league-capability gaps, with machine-readable league and capability fields.

2026-04-02 · additive

• MLB play-by-play with Statcast pitch-level metrics.
• New detail=sparse|standard|full query param to trade payload size for field coverage.

2026-03-10 · additive

• NFL and NHL added to the normalized schema. NBA and MLB were live previously.
• New endpoints: /v1/competitions/{comp}/editions/{year}/standings, /v1/teams/{team_id}/roster, and /v1/competitions/{comp}/editions/{year}/games.

2026-02-22 · v1.0: initial release

• REST API with NBA + MLB normalized box scores, season stats, and player search.
• Hosted MCP server at mcp.statshawk.ai with OAuth sign-in.
• Plans: free / hobby / pro / scale / growth / enterprise.

Subscribing

We post a short note to the Statshawk blog on every change here. For breaking changes (version bumps) we will also email registered accounts at least 60 days before cut-over.