# Magisterial API changelog

Release notes for the /v1 developer API, newest first. Policy: at least 90
days' notice before any breaking change to /v1, announced here with
Deprecation and Sunset response headers on affected endpoints.

Human version with anchors: https://magisterial.ai/changelog

## 2026-07-21 — Games listing, coaching staffs, and bulk exports
Tags: added, changed

- GET /v1/games is live: list games in a sport/division scope, newest first, with team, season, date-range, and status filters. One row per real-world game, side-anchored (home/away), with team ids — no more perspective-duplicated rows.
- GET /v1/teams/{team_id}/coaches is live: the coaching staff for a team-season, head coach first, defaulting to the latest season held. Coach email is included for Pro/Max accounts only, matching the portal-contacts carve-out.
- Behavior change on GET /v1/games/{game_id}: game ids now come from our fixture store — the same ids GET /v1/games returns and /v1/query answers reference (previously the two id spaces did not match). Ids fetched before today no longer resolve; re-list via GET /v1/games. The payload is richer: the fixture under detail.game plus team and player box scores, play-by-play, and per-sport extras (drives, recaps).
- Bulk exports: POST /v1/exports starts an async job that writes players, teams, games, or coaches for one sport/division scope to a gzipped CSV or JSONL flat file; GET /v1/exports/{export_id} returns a short-lived signed download URL when it succeeds. Usage-billed on success by result size ($0.10 per started 10,000-row block); failed exports are never billed. Files are kept for 7 days.

Links: Games docs: https://magisterial.ai/docs#get-games · Bulk exports docs: https://magisterial.ai/docs#exports

## 2026-07-21 — Interactive docs, retrievable test keys, and this changelog
Tags: added, changed

- The API reference at /docs is now interactive: sign in and every example is pre-filled with your own test key, with a Run it button that sends real requests from the browser and shows status, latency, and rate-limit headers.
- Test keys (mag_test_) are now retrievable: the docs playground fetches your newest test key automatically (minting a "Docs playground" key on first visit), and test-key tokens are stored encrypted so they can be re-shown. Live keys remain visible only once, at creation.
- Behavior change for test keys: they now return 403 test_key_paid_endpoint on the usage-billed endpoints (/v1/portal, /v1/query, /v1/alerts). All free read endpoints keep working unchanged, so a test key can never create charges.
- Published our versioning and deprecation policy — at least 90 days' notice before any breaking change to /v1, with Deprecation and Sunset response headers on affected endpoints.

Links: Authentication docs: https://magisterial.ai/docs#authentication · Deprecation policy: https://magisterial.ai/changelog#policy

## 2026-07-21 — Coverage endpoint and published OpenAPI spec
Tags: added

- GET /v1/coverage: the full data-coverage matrix — per sport and division, how many teams, coaches, games, and players we hold, with season ranges and transfer-portal tracking counts. Free at the standard read rate limit; use it to confirm coverage before issuing billed requests.
- The complete API contract is now published as OpenAPI 3.1 at https://api.magisterial.ai/v1/openapi.json, with an interactive rendering at https://api.magisterial.ai/v1/docs. Import it into Postman, generate typed clients, or hand it to an agent.

Links: Coverage endpoint docs: https://magisterial.ai/docs#get-coverage

## 2026-07-20 — Rich cards in the Claude connector; billing accuracy fixes
Tags: added, fixed

- The MCP connector now returns rich inline widgets in claude.ai: player and coach cards with headshots and season stats, and results tables with charts.
- Fixed token accounting on /v1/query: prompt-cache activity is now billed correctly end-to-end, and a double-billing path for /v1 runs was closed. If you saw slightly inconsistent billed_usd values on query runs before this date, this is why.

Links: Connectors: https://magisterial.ai/connectors

## 2026-07-15 — Football opens on /v1; web-search-augmented queries
Tags: added, changed

- Football is now queryable through the public API, including the D1-FBS and D1-FCS subdivisions and 3C2A, everywhere a division scope is accepted.
- Natural-language query runs can now consult the web to fill gaps (recent news, off-dataset context) when the account's plan includes it, and inline coach cards appear in answers where relevant.

## 2026-07-13 — Developer platform launch
Tags: added

- API keys (live and test) managed from the developer console, with rotate and revoke.
- The /v1 API: players search and profiles, season stats, teams and rosters, cross-program careers and transfers, games, conferences, and the filter catalog — free at 120 requests/minute.
- Usage-billed endpoints with a monthly budget cap you control: the live transfer-portal feed ($0.05/request), natural-language query (model cost with markup), and portal watch alerts ($5/alert/month) with match polling.
- MCP server with OAuth 2.1 at https://api.magisterial.ai/mcp, so Claude and other MCP clients can use Magisterial directly.

Links: API reference: https://magisterial.ai/docs · Pricing: https://magisterial.ai/pricing