# Magisterial API documentation

Programmatic access to Magisterial's college sports data — players, season
stats, teams, rosters, coaching staffs, games, cross-program careers and
transfers, the live NCAA transfer portal, natural-language query, and bulk
exports. Seven sports (soccer, basketball, baseball, softball, volleyball,
football, track and field) across NCAA D1/D2/D3 (incl. FBS/FCS), NAIA, NJCAA.

## The canonical references

- Complete API reference as one markdown document (recommended for agents —
  auth, scoping, pagination, errors, every endpoint and object shape):
  https://api.magisterial.ai/v1/llms.txt
- OpenAPI 3.1 spec: https://api.magisterial.ai/v1/openapi.json
- Interactive human reference: https://api.magisterial.ai/v1/docs
  (mirrored at https://magisterial.ai/docs with sign-in-aware, runnable examples)

## Quickstart

No key needed for the coverage matrix:

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

Everything else takes a bearer key (self-serve at https://magisterial.ai/console):

    curl https://api.magisterial.ai/v1/teams?sport=soccer&division=D3&gender=men \
      -H "Authorization: Bearer mag_live_..."

- Free read endpoints: 120 requests/minute (players, teams, games, coaches,
  careers, reference data, coverage).
- Test keys (mag_test_) hit the free read endpoints for real and are blocked
  from usage-billed endpoints, so development can never create charges.
- Usage-billed: /v1/portal ($0.05/request), /v1/query (model cost with
  markup), /v1/alerts ($5/alert/month), /v1/exports ($0.10 per started
  10,000-row block) — all under a monthly budget cap you control.

## Other surfaces

- SDKs (Python + TypeScript): https://magisterial.ai/sdk.md
- MCP connector for AI assistants: https://magisterial.ai/connectors.md
- Agent guide: https://magisterial.ai/agents.md
- API changelog + deprecation policy (90 days' notice on /v1 breaking
  changes, Deprecation/Sunset headers): https://magisterial.ai/changelog.md