magisterialmagisterialDocs

Changelog

Release notes and deprecation notices for the developer API. Anything that changes how your integration behaves lands here first.

Versioning & deprecation policy

The API is versioned by URL prefix; /v1 is the current and only version.

Additive changes ship without notice. New endpoints, new response fields, new optional parameters, and new enum values may appear at any time. Write clients that tolerate unknown fields and unrecognized enum values.

Breaking changes get at least 90 days’ notice. Removing or renaming a field, changing a field’s type or meaning, removing an endpoint, tightening validation, or changing authentication all count as breaking. Before any of these take effect on /v1 we will: (1) announce it here with a deprecated entry, (2) email every account with an active API key, and (3) begin sending a Deprecation header (RFC 9745) on affected responses, with a Sunset header (RFC 8594) giving the exact retirement date and a Link rel="deprecation" header pointing at the announcement on this page.

Fixes are exempt only when the documented behavior was already correct — we may fix responses that violate the documented contract without a deprecation window.

July 2026
addedchanged

Games listing, coaching staffs, and bulk exports

  • —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.
Games docs →Bulk exports docs →
addedchanged

Interactive docs, retrievable test keys, and this changelog

  • —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.
Authentication docs →Deprecation policy →
added

Coverage endpoint and published OpenAPI spec

  • —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.
Coverage endpoint docs →
addedfixed

Rich cards in the Claude connector; billing accuracy fixes

  • —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.
Connectors →
added

Developer platform launch

  • —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.
API reference →Pricing →
Building against the API? Read the reference or grab the OpenAPI spec.