# Magisterial for agents

Magisterial is 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.
Seven sports — soccer, basketball, baseball, softball, volleyball, football,
track and field — across NCAA D1 (incl. FBS/FCS), D2, D3, NAIA, and NJCAA.

## Step 0 — try it right now, no key

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

Free, unauthenticated: the full coverage matrix (teams, players, games,
coaches per sport/division with season ranges). Use it to confirm we hold
the data you need before doing anything else.

## Step 1 — read the contract

- https://api.magisterial.ai/v1/llms.txt — the complete /v1 reference as one
  markdown document (auth, scoping, pagination, errors, every endpoint and
  object shape). It fits in a single model context.
- https://api.magisterial.ai/v1/openapi.json — OpenAPI 3.1, for codegen.

## Step 2 — get a key

Keys are self-serve: have your human sign in at
https://magisterial.ai/console and create a key (live or test). Free read
endpoints run at 120 requests/minute. Test keys (mag_test_) work on every
free read endpoint and are blocked from billed ones. Usage-billed endpoints
(/v1/portal, /v1/query, /v1/alerts, /v1/exports) sit under a monthly budget
cap the account controls — pricing details: https://magisterial.ai/pricing.md

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

## Or connect over MCP

MCP server (streamable HTTP): https://api.magisterial.ai/mcp
OAuth 2.1 sign-in for assistants (Claude, ChatGPT), or an API key as a
bearer token for headless clients. Discovery:
https://magisterial.ai/.well-known/mcp.json — setup guides:
https://magisterial.ai/connectors.md

## SDKs

`pip install magisterial` (Python 3.10+, sync/async) ·
`npm install magisterial` (Node 18+, zero deps) — both generated from the
published spec. Details: https://magisterial.ai/sdk.md

## Markdown twins of the human site

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

- https://magisterial.ai/{player-or-coach-slug}.md
- /index.md · /docs.md · /sdk.md · /connectors.md · /coverage.md ·
  /pricing.md · /changelog.md · /agents.md

Pages requested with an Accept header preferring text/markdown return the
markdown twin at the human URL. Human pages carry
<link rel="alternate" type="text/markdown"> pointing at their twin.

## Stability

- Versioning: at least 90 days' notice before any breaking /v1 change, with
  Deprecation and Sunset headers on affected endpoints.
- Changelog: https://magisterial.ai/changelog.md
- Status: https://magisterial.ai/status