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.

September 2026
changedadded

Portal API opens on the Developer plan; entries link to player records

  • —GET /v1/portal is now open on the Developer plan (or Enterprise) with API billing enabled; the Max coaching plan for the sport is no longer required. The key still needs the portal.entry.read scope and must belong to an active verified coach, and athlete contacts still require portal.contact.read. Per-request pricing is unchanged.
  • —Portal entries now carry player_id and person_id, linking each athlete to their player record (GET /v1/players/{player_id}) and cross-program career (GET /v1/persons/{person_id}). Both are null when an entry is not yet linked. The fields are additive; existing clients are unaffected.
  • —API portal alerts are unchanged and still follow the coaching-plan policy.
Portal API docs →
addedchanged

Schools, freshness, movement tiers, and managed athletes

  • —GET /v1/teams and GET /v1/teams/{team_id} now include a school object (id, slug, athletics domain, and the federal IPEDS UNITID); list teams can also filter to one school with ?ipeds_unitid=. New GET /v1/schools and GET /v1/schools/{school_id} endpoints look institutions up directly and list every program a school fields, cross-sport and cross-division.
  • —Record-level freshness: GET /v1/teams/{team_id} adds a freshness object per data kind (roster, coaches, season_stats, schedule), and the roster and coaching-staff endpoints add their own freshness plus contacts_included on coaches. GET /v1/coverage adds a freshness snapshot of ingest-lane runs and the seasonal cadence policy.
  • —GET /v1/movements gains a status parameter: published (curated, every plan, unchanged default), resolved and observed (Enterprise, the underlying resolver stream). Entries now carry status, resolution_status, resolved_at, school_id, and ipeds_unitid.
  • —GET /v1/teams/{team_id}/coaches gains on_behalf_of, letting an Enterprise key read coach contacts on a managed athlete's behalf; each delegated read is recorded in the athlete's access log. Not metered.
  • —Custom Enterprise plans can include the coach directory outright: with coach_contact_directory on the plan, a key carrying the exact coach.contact.directory_read scope reads coach contacts without on_behalf_of, like any other read. Coach opt-outs are honored and contact fields never appear in bulk exports.
  • —Python and TypeScript SDKs 0.5.0 add schools and athletes resources, the ipeds_unitid team filter, the movements status tier, and on_behalf_of on team coaches.
  • —New Managed athletes endpoints (Enterprise, managed_athlete.manage key scope): POST /v1/athletes invites a player to authorize your account, GET /v1/athletes and GET /v1/athletes/{grant_id} list and fetch grants, POST /v1/athletes/{grant_id}/resend and DELETE /v1/athletes/{grant_id} manage them, and GET /v1/athletes/{grant_id}/access is the per-athlete audit log.
Schools docs →Data sources & freshness →Managed athletes →
changed

Developer plan is sold on its own; new Developer API pricing page

  • —Max subscriptions no longer include the Developer API plan. The Developer plan ($99.99 per month) is bought from Console -> Billing or arranged as part of an Enterprise agreement; every other account, whatever its coaching plan, is on Free (10 requests per minute, 1,000 per month). Accounts that already held keys before the plan ladder launched were kept on Developer by hand.
  • —Developer API pricing has its own page at /pricing/developers (and /pricing/developers.md for agents). The Pricing tab in the developer navigation now points there; /pricing keeps the per-sport coaching plans.
Developer API pricing →Plans in the docs →
addedchanged

API plans: Free, Developer, and Enterprise

  • —Every API key now inherits its owner's plan. Free ($0, every account) reads at 10 requests per minute and 1,000 requests per calendar month, with the usage-billed endpoints closed. Developer ($99.99 per month, included with every Max subscription) reads at 300 requests per minute and 250,000 per month and opens the transfer portal, natural-language query, alerts, and bulk exports at their list prices. Enterprise is a per-customer agreement with custom limits and no monthly cap.
  • —Free-plan calls to /v1/portal, /v1/query, /v1/alerts, and /v1/exports return 403 plan_required. Exceeding a plan's monthly quota returns 429 monthly_quota_exceeded with quota, used, and resets_at; every response carries X-Magisterial-Plan and capped plans add X-Monthly-Quota-Limit and X-Monthly-Quota-Remaining.
  • —The previous single limit of 120 requests per minute is retired. Keys on accounts without Max drop to the Free limits; upgrade to Developer from Console -> Billing. Buying Developer enables usage billing on the same subscription.
  • —Alert counts, in-flight query and export ceilings, and the export row cap are now per plan (Developer: 25 alerts, 3 queries and 2 exports in flight, 500,000 rows per export).
Plans & pricing →Console billing →
August 2026
added

Season-scoped rosters and SDKs 0.4.0

  • —GET /v1/teams/{team_id}/roster now accepts an optional four-digit season and returns the selected season on every page, while continuing to default to the latest roster held.
  • —Python and TypeScript SDKs 0.4.0 expose the season parameter, retain it across cursor pagination, and surface the response season on each page.
Roster API docs →SDK documentation →
changedfixed

Portal API authorization is now explicit and subscription-bound

  • —GET /v1/portal and API portal alerts now require both usage billing and current application authority: an active verified coach, the Max plan for the requested sport, and an exact delegated portal capability on the key. API billing alone no longer grants portal access.
  • —Athlete contacts require the separate portal.contact.read scope under the same current actor and sport policy. Keys are intersected with current authority on every request; role changes, downgrades, scope reduction, and revocation take effect without recreating the account session.
  • —The response schema and SDK method signatures are unchanged. Existing keys that depended on implicit owner-full authority must be recreated or assigned reviewed exact scopes in the developer console.
  • —Stored portal notifications, chats, runs, cards, and drafts are reauthorized or sanitized on every read and are retained but unreadable after authority loss. Previously delivered email cannot be recalled; all future evaluation and delivery stops until authority is restored.
Portal API docs →
added

Movements feed: confirmed coaching changes and transfers

  • —GET /v1/movements is live: a published feed of roster and coaching-staff movements — confirmed head-coach changes and corroborated transfers — newest first. Cross-division with no scope parameters; filter by kind (player or coach), sport path, and a since timestamp; cursor-paginated. Entries carry a display snapshot of the person (never contact info) plus person and transfer ids that join into /v1/persons and transfer histories.
  • —Entries are curated: an event only appears once our pipeline confirms it (portal-corroborated transfers, verified head-coach changes) or an editor publishes it — this is not the raw scraper diff stream.
  • —SDKs 0.3.0 (PyPI and npm) add the movements resource: client.movements.list(...) in both.
Movements docs →
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.