# Magisterial

> College sports data, built to be consumed by agents. Rosters, player and
> team season statistics, games and play-by-play, coaching staffs, careers
> and transfers, accolades, and live NCAA transfer-portal tracking across
> seven sports — soccer, basketball, baseball, softball, volleyball,
> football, and track and field — at every level of college athletics:
> NCAA Division I (incl. FBS/FCS), II, and III, the NAIA, and the NJCAA.

## Start here (no key needed)

Confirm we hold the data you need — free, unauthenticated:

    curl https://api.magisterial.ai/v1/coverage

Returns the full coverage matrix: teams, players, games, and coaches per
sport and division, with season ranges and transfer-portal counts.

## Full API reference

- https://api.magisterial.ai/v1/llms.txt — the complete /v1 contract as one
  markdown document (auth, scoping, pagination, errors, every endpoint and
  object shape). Fits in a single model context; read this before coding.
- https://api.magisterial.ai/v1/openapi.json — OpenAPI 3.1 spec.
- https://api.magisterial.ai/v1/docs — interactive human reference.

## Get a key

Self-serve at https://magisterial.ai/console (sign-up takes a minute).
Free read endpoints run at 120 requests/minute. Test keys (mag_test_) work
on every free read endpoint and are blocked from billed ones, so development
can never create charges. Usage-billed endpoints (/v1/portal, /v1/query,
/v1/alerts, /v1/exports) sit under a monthly budget cap the account
controls. Pricing: https://magisterial.ai/pricing.md

## MCP

- Server (streamable HTTP): https://api.magisterial.ai/mcp
- Auth: OAuth 2.1 for assistants (Claude, ChatGPT), or an API key as a
  bearer token for headless clients.
- Discovery: https://magisterial.ai/.well-known/mcp.json and
  https://api.magisterial.ai/.well-known/oauth-authorization-server
- Setup guides: https://magisterial.ai/connectors.md

## SDKs

- Python 3.10+ (sync/async): pip install magisterial
- TypeScript/JavaScript, Node 18+: npm install magisterial
- Details and quickstarts: https://magisterial.ai/sdk.md

## Markdown pages

Append .md to any key magisterial.ai page URL for the agent-readable
version — including every public player and coach profile page:

- https://magisterial.ai/{player-or-coach-slug}.md
- https://magisterial.ai/index.md (about Magisterial)
- https://magisterial.ai/agents.md (agent guide — the long version of this file)
- https://magisterial.ai/docs.md · /sdk.md · /connectors.md · /coverage.md ·
  /pricing.md · /changelog.md

Requests with an Accept header preferring text/markdown get the markdown
twin at the human URL.

## Stability and status

- At least 90 days' notice before breaking /v1 changes (Deprecation and
  Sunset headers): https://magisterial.ai/changelog.md
- Status page: https://magisterial.ai/status