# Dynasty Rewired developer documentation

> Dynasty Rewired is an independent companion site for College Football 27 (CFB 27) dynasties: online dynasties through its in-game tracking account, offline dynasties and Road to Glory careers from a Windows PC. This file holds the complete developer documentation: the read-only REST API at https://dynastyrewired.com/api/developer/v1 (personal bearer token) and the league webhook export. OpenAPI: https://dynastyrewired.com/developer/openapi.json. Static test delivery: https://dynastyrewired.com/developer/webhook-sample.json.

# College Football 27 Dynasty API and Webhooks

Source: https://dynastyrewired.com/developer

Dynasty Rewired has a read-only REST API and webhooks for College Football 27 (CFB 27) dynasties. Read your league’s saved data as JSON, from schedules, scores and standings to box scores, polls, recruiting, coaches, awards and full rosters with ratings, and build a Discord bot, a league site or your own archive on it.

## Two ways to get your data

|  | REST API | Webhook export |
| --- | --- | --- |
| What it does | Your code asks for a league’s data whenever it wants | Dynasty Rewired sends each new capture to your server |
| Set up by | Any member, with a personal token from [Account → API access](https://dynastyrewired.com/account#api-access) | The league owner, in League settings → Webhook |
| Covers | Every league you own, have private access to or follow | One league, one HTTPS endpoint |
| Best for | Scripts, spreadsheets, bots that look things up | Keeping your own copy or site up to date automatically |

Both return the same JSON documents. A webhook delivery’s `data` is exactly what the matching API request returns at that moment, so code written for one works with the other.

## Quick start

1. Create a token at [Account → API access](https://dynastyrewired.com/account#api-access). Copy it right away: it is shown only once.
2. List your leagues. Each league’s `id` (like `cfb27-815166`) is the last part of its page address.
3. Request a dataset for a season, or use `current` for the league’s current season.
4. Optional, for league owners: open League settings → Webhook, paste your server’s https:// URL, save, copy the signing secret and press **Send test delivery**.

**Try it**

```bash
export DR_API_TOKEN="drk_…"
curl -H "Authorization: Bearer $DR_API_TOKEN" https://dynastyrewired.com/api/developer/v1/leagues
curl -H "Authorization: Bearer $DR_API_TOKEN" https://dynastyrewired.com/api/developer/v1/leagues/cfb27-815166/seasons/current/schedule
```

## Set it up with an AI agent

Coding agents such as Claude Code, Codex and Cursor can build an integration from one prompt. Point them at [llms.txt](https://dynastyrewired.com/developer/llms.txt): it holds this whole documentation as a single Markdown file. Keep your token and signing secret in environment variables, never in the prompt or in a public repository.

**Prompt: export my league to files**

```text
Read the Dynasty Rewired developer docs at https://dynastyrewired.com/developer/llms.txt.
Write a Python script that uses my API token from the DR_API_TOKEN environment variable to
download the current season's schedule, rankings, coaches and awards for league cfb27-815166,
save each one as JSON, and write standings.csv from the schedule's teams.
Handle 402 (trial ended) and 429 (rate limited) responses the way the docs describe.
```

**Prompt: keep my own copy with a webhook**

```text
Read the Dynasty Rewired developer docs at https://dynastyrewired.com/developer/llms.txt.
Build a small Node.js server that receives my league's webhook deliveries at POST /dynasty-rewired.
Verify the X-DR-Signature header against the raw body with the secret in DR_WEBHOOK_SECRET and
reject deliveries older than five minutes. Reply 200 right away, then save season documents to
data/<league>/<season>/<dataset>.json, box scores to .../box-scores/<gameId>.json and rosters to
.../rosters/<teamId>.json. Log test deliveries ("test": true) without saving them. Add a script that
replays https://dynastyrewired.com/developer/webhook-sample.json against the server with a valid signature.
```

**Prompt: post user-vs-user finals to Discord**

```text
Read the Dynasty Rewired developer docs at https://dynastyrewired.com/developer/llms.txt.
Create a Cloudflare Worker that receives my league's Dynasty Rewired webhooks and verifies them with
DR_WEBHOOK_SECRET. When a schedule delivery arrives, post every newly final game between two
user-controlled teams to the Discord webhook in DISCORD_WEBHOOK_URL as "Away score at Home score".
Remember posted gameIds in KV so a repeated delivery never posts twice.
```

## Access, trials and subscriptions

- A token reads the leagues on your dashboard: leagues you own, private leagues you have been granted access to, and public leagues you follow.
- The API and webhooks work for every active league, including during the free trial.
- When a league’s free trial ends without a subscription, API requests for that league return `402 SUBSCRIPTION_REQUIRED` and its webhook pauses. The league’s saved pages stay readable on the website, and both resume once the owner subscribes.
- The API is read-only. Owners manage webhooks on the website; the API can only read a webhook’s status and send its test delivery.
- Each token can make up to 60 requests a minute and 2,000 a day. Webhooks have no daily limit: they send only when data changes.

## Reference

- [How to use the CFB 27 dynasty API](https://dynastyrewired.com/guides/use-the-cfb-27-dynasty-api): a step-by-step tutorial from a new token to your league’s schedule, box scores and rosters.
- [REST API](https://dynastyrewired.com/developer/api): authentication, endpoints, errors and limits.
- [Webhooks](https://dynastyrewired.com/developer/webhooks): delivery format, signatures, retries and the test delivery.
- [Data reference](https://dynastyrewired.com/developer/data): every field, plus stat and rating code glossaries.
- Machine-readable: [llms.txt](https://dynastyrewired.com/developer/llms.txt) (all docs as Markdown), [openapi.json](https://dynastyrewired.com/developer/openapi.json) (OpenAPI 3.1) and [webhook-sample.json](https://dynastyrewired.com/developer/webhook-sample.json) (the static test delivery).

## Questions

### Is there an API for College Football 27 dynasties?

Yes. Dynasty Rewired’s read-only REST API returns the data it saves from a College Football 27 dynasty as JSON, and its webhooks send each new capture to your own server. Dynasty Rewired is independent and is not affiliated with, endorsed by or sponsored by Electronic Arts or EA SPORTS.

### What league data can I read?

Schedules and final scores, team records and standings, box scores with team and player stats, media, coaches and playoff polls, the playoff bracket and champions, the recruit pool and class rankings, user coaches, season awards, and full rosters with ratings and abilities. The [data reference](https://dynastyrewired.com/developer/data) lists every field.

### Can I build a Discord bot with it?

Yes. A bot can look up schedules, scores and standings with your token, or have the league’s webhook send each capture to your server and post what you choose; the [AI agent prompts](https://dynastyrewired.com/developer#ai-agents) include one that posts every final between two user-controlled teams. For week-advance alerts alone you need no code: Dynasty Rewired’s own Discord bot posts them to the channel you pick.

### Do I need my own league to use the API?

No. A token reads every league on your dashboard: leagues you own, private leagues you have been given access to and public leagues you follow. Follow a public league from [Browse dynasties](https://dynastyrewired.com/dynasties) and your token can read it.

### Does it cover offline dynasties and Road to Glory?

Yes. Offline dynasties and Road to Glory careers synced from a Windows PC, with the [Offline Sync app](https://dynastyrewired.com/offline-sync) or a save upload, are read the same way as online dynasties. Values a save does not hold are `null`, and a dataset with nothing saved answers with empty lists.

### Which College Football games are supported?

College Football 27. Dynasties from College Football 25 and College Football 26 are not supported.

### What does the API cost?

Nothing extra. The API and webhooks work for every active league, including during its free trial. When a league’s trial ends without a subscription, its requests return `402` until the owner subscribes (see [pricing](https://dynastyrewired.com/pricing)). Each token can make 60 requests a minute and 2,000 a day.

# College Football 27 Dynasty REST API Reference

Source: https://dynastyrewired.com/developer/api

Read-only JSON over HTTPS for College Football 27 dynasties, online and offline. Every request needs your personal token.

## Base URL and authentication

**Base URL**

```text
https://dynastyrewired.com/api/developer/v1
```

Send your token in the `Authorization` header on every request. Create, replace or revoke it at [Account → API access](https://dynastyrewired.com/account#api-access).

```http
Authorization: Bearer drk_…
```

- Each account has one token, and it works for all of your leagues. Creating a new token replaces the old one immediately.
- Tokens start with `drk_`. Dynasty Rewired stores only a fingerprint, so a lost token cannot be shown again: create a new one.
- Call the API from a server, script or bot. Browsers cannot call it directly, which keeps your token out of web pages.

## Leagues and seasons

A league’s `id` is the last part of its page address: `https://dynastyrewired.com/leagues/cfb27-815166` is league `cfb27-815166`. List yours with `GET /leagues`.

Seasons are four-digit years such as `2028`. Use `current` for the league’s current season. `GET /leagues/{league}` lists every season with saved data.

## Endpoints

| Method and path | Returns |
| --- | --- |
| `GET /leagues` | Leagues your token can read, with your role and each league’s access |
| `GET /leagues/{league}` | League summary: seasons, current stage, tracking state and available datasets |
| `GET /leagues/{league}/seasons/{season}/schedule` | Weeks, games, scores and team records/standings |
| `GET /leagues/{league}/seasons/{season}/box-scores` | Accepted box scores, 20 per page (`after`, `limit`) |
| `GET /leagues/{league}/seasons/{season}/box-scores/{gameId}` | One game’s box score |
| `GET /leagues/{league}/seasons/{season}/rankings` | Media, coaches and playoff polls by week |
| `GET /leagues/{league}/seasons/{season}/postseason` | Playoff bracket and national championships |
| `GET /leagues/{league}/seasons/{season}/recruiting` | Recruit pool and team class rankings |
| `GET /leagues/{league}/seasons/{season}/coaches` | User head coaches and coordinators, active and departed |
| `GET /leagues/{league}/seasons/{season}/awards` | Season award winners |
| `GET /leagues/{league}/seasons/{season}/rosters` | Roster captures (runs) and which schools each captured |
| `GET /leagues/{league}/seasons/{season}/rosters/{teamId}` | One school’s players, ratings and abilities (`run` optional) |
| `GET /leagues/{league}/webhook` | Owners only: the league webhook’s status (never its secret) |
| `POST /leagues/{league}/webhook/test` | Owners only: send the static test delivery to the webhook |

Without `run`, a school’s roster comes from the newest roster capture that includes it. Field-by-field contents are in the [data reference](https://dynastyrewired.com/developer/data).

## Responses

League requests return an envelope. `data` holds the dataset; its shape is in the [data reference](https://dynastyrewired.com/developer/data).

```json
{
  "league": {"id": "cfb27-815166", "name": "TeamCrafters", "url": "https://dynastyrewired.com/leagues/cfb27-815166"},
  "season": 2028,
  "dataset": "schedule",
  "data": { "state": "available", "weeks": [ … ], "teams": [ … ] }
}
```

- Times are Unix epoch **milliseconds** (UTC), such as `capturedAt: 1793000000000`.
- IDs (`teamId`, `gameId`, `playerId`, `recruitId`) are strings.
- Football values are kept exactly as EA sent them. Names, records and codes are never rewritten, and a value we did not capture is `null`, not zero.
- New fields can appear at any time. Ignore fields you do not use; existing fields keep their meaning within `v1`.
- A dataset with nothing saved yet still answers `200` with empty lists and a `state` such as `pending` or `unavailable`.

### Box score pages

Box scores come 20 at a time in `gameId` order. When `next` is not null, pass it as `after` to read the next page.

```http
GET /leagues/cfb27-815166/seasons/2028/box-scores?limit=20
→ {"data": {"games": [ … ], "next": "2741"}}
GET /leagues/cfb27-815166/seasons/2028/box-scores?after=2741
```

## Errors

```json
{"error": {"code": "SUBSCRIPTION_REQUIRED", "message": "This league's free trial has ended. …", "requestId": "4c1e…"}}
```

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | A query parameter is not allowed or out of range |
| 401 | `UNAUTHORIZED` | The token is missing, malformed, replaced or revoked |
| 402 | `SUBSCRIPTION_REQUIRED` | The league’s free trial has ended; the owner can subscribe to resume |
| 403 | `OWNER_ONLY` | Only the league owner can use this webhook endpoint |
| 404 | `NOT_FOUND` | Unknown endpoint, league, game or school, or a league you cannot read |
| 409 | `NOT_CONFIGURED` | The league has no webhook yet |
| 429 | `RATE_LIMITED` | Over the per-minute or daily limit (wait for `Retry-After`), or under 10 seconds between webhook tests |
| 502 | `DELIVERY_FAILED` | The webhook test reached your server, which did not answer 2xx |
| 503 | `UNAVAILABLE` | Temporarily unavailable; retry with backoff |

Include the `requestId` (also in the `X-Request-Id` header) when you ask for help.

## Rate limits and polling

- Up to **60 requests a minute** and **2,000 requests a day** per token. The daily count resets at midnight UTC, and replacing your token does not reset it.
- Every authorized response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds when the daily count resets). Over a limit, the API answers `429 RATE_LIMITED` with a `Retry-After` header in seconds.
- 2,000 requests cover a full backfill of five seasons (season documents, every box score page and every school roster, about 1,000 requests) with room to spare. Your daily count appears under Account → API access.
- League data changes only when the tracker saves a new capture, usually right after the league advances. Polling more often than every five minutes gains nothing.
- For change notifications use a [webhook](https://dynastyrewired.com/developer/webhooks) instead of polling.

## Examples

**JavaScript (Node 18+)**

```javascript
const base = "https://dynastyrewired.com/api/developer/v1";
const headers = {Authorization: `Bearer ${process.env.DR_API_TOKEN}`};
const get = async path => {
  const response = await fetch(base + path, {headers});
  if (!response.ok) throw new Error((await response.json()).error.message);
  return response.json();
};
const {data: leagues} = await get("/leagues");
const {data: schedule} = await get(`/leagues/${leagues[0].id}/seasons/current/schedule`);
for (const week of schedule.weeks)
  for (const game of week.games.filter(g => g.status === "final"))
    console.log(week.label, `${game.awayName} ${game.awayScore} at ${game.homeName} ${game.homeScore}`);
```

**Python**

```python
import os, requests
base = "https://dynastyrewired.com/api/developer/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['DR_API_TOKEN']}"

def box_scores(league, season):
    after = None
    while True:
        params = {"after": after} if after else {}
        page = session.get(f"{base}/leagues/{league}/seasons/{season}/box-scores", params=params).json()["data"]
        yield from page["games"]
        if not page["next"]:
            return
        after = page["next"]

for game in box_scores("cfb27-815166", "current"):
    print(game["gameId"], game["game"]["awayName"], "at", game["game"]["homeName"])
```

# College Football 27 Dynasty Webhooks

Source: https://dynastyrewired.com/developer/webhooks

A league owner can send a copy of everything Dynasty Rewired saves for a College Football 27 league to one HTTPS endpoint.

## How it works

- Each league has at most one webhook, set up by its owner in League settings → Webhook.
- When you turn a webhook on, or point it at a new URL, it first receives a **full copy**: every dataset for every season the league has saved.
- After that, each time the tracker saves new data, the changed datasets arrive within about a minute.
- Each POST carries one dataset for one season. A season document (schedule, rankings, postseason, recruiting, coaches, awards) is always complete. Box scores arrive up to 20 games at a time, and rosters up to five schools from one roster capture.
- Up to ten deliveries go out per league each minute, so a large league’s first full copy can take several minutes.

## Set up

1. Run a receiver at a public `https://` URL on the standard port (443). For local development, use a tunnel such as Cloudflare Tunnel or ngrok.
2. Open your league’s Settings, find **Webhook**, enter the URL and save.
3. Copy the signing secret (`whsec_…`) into your receiver’s configuration. You can reveal or rotate it later.
4. Press **Send test delivery** and check that your receiver answered `2xx`.

## Delivery format

Each delivery is a `POST` with a JSON body:

```json
{
  "id": "0f8e8a3e-5d3b-4c55-9f0e-6f0f6b1a2c3d",
  "type": "dataset.updated",
  "createdAt": 1793000000000,
  "test": false,
  "league": {"id": "cfb27-815166", "name": "TeamCrafters", "url": "https://dynastyrewired.com/leagues/cfb27-815166"},
  "dataset": "schedule",
  "season": 2028,
  "data": { … exactly what GET /leagues/cfb27-815166/seasons/2028/schedule returns … }
}
```

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |
| `User-Agent` | `DynastyRewired-Webhooks/1.0` |
| `X-DR-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256>`, described below |
| `X-DR-Event` | `dataset.updated` |
| `X-DR-Dataset` | The dataset name, such as `schedule` |
| `X-DR-Delivery` | A unique ID for this attempt |
| `X-DR-Test` | `true` on test deliveries only |

| `dataset` | `data` |
| --- | --- |
| `schedule` | The season’s [schedule document](https://dynastyrewired.com/developer/data#schedule) |
| `rankings` | The season’s [rankings document](https://dynastyrewired.com/developer/data#rankings) |
| `postseason` | The season’s [postseason document](https://dynastyrewired.com/developer/data#postseason) |
| `recruiting` | The season’s [recruiting document](https://dynastyrewired.com/developer/data#recruiting) |
| `coaches` | The season’s [coaches document](https://dynastyrewired.com/developer/data#coaches) |
| `awards` | The season’s [awards document](https://dynastyrewired.com/developer/data#awards) |
| `box-scores` | `{"games": [box score, …]}`, up to 20 [box scores](https://dynastyrewired.com/developer/data#box-scores) |
| `rosters` | `{"runId": "…", "schools": [school roster, …]}`, up to five [school rosters](https://dynastyrewired.com/developer/data#rosters) from one capture |

## Verify the signature

Compute an HMAC-SHA256 of `<t>.<raw body>` with your signing secret (the whole `whsec_…` string) and compare it, in constant time, with the hex `v1` value. Use the raw request bytes: parsing and re-serializing the JSON changes them. Reject a timestamp more than five minutes old.

**Node.js**

```javascript
import crypto from "node:crypto";

export function verifyDynastyRewired(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(signatureHeader.split(",").map(part => part.split("=")));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

// Express: keep the raw body for verification.
app.post("/dynasty-rewired", express.raw({type: "application/json", limit: "25mb"}), (req, res) => {
  if (!verifyDynastyRewired(req.body.toString("utf8"), req.get("X-DR-Signature") ?? "", process.env.DR_WEBHOOK_SECRET))
    return res.sendStatus(401);
  res.sendStatus(200);
  const delivery = JSON.parse(req.body);
  // Save delivery.data for delivery.league.id, delivery.dataset and delivery.season.
});
```

**Python**

```python
import hashlib, hmac, time

def verify_dynasty_rewired(raw_body: bytes, signature_header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(part.split("=", 1) for part in signature_header.split(",") if "=" in part)
    try:
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))
```

## Responses, retries and duplicates

- Answer with any `2xx` status within 10 seconds. Store the body and do slow work afterwards.
- Anything else is a failure: another status, a timeout, a connection error or a redirect. Redirects are not followed, so use the final URL.
- After a failure, delivery for that league pauses and retries 30 seconds later, doubling up to once an hour. Nothing is skipped: the undelivered data is sent when your server recovers.
- After 10 failures in a row, the league owner and every league manager get a notice on Dynasty Rewired and an email. The next delivery your server accepts clears it.
- After 50 failures in a row, the webhook turns itself off, and they hear about that too. Turn it on again in League settings to receive a fresh full copy.
- Delivery is at least once, and order between datasets is not guaranteed. Save by key and overwrite: season documents by league, dataset and season; box scores by `gameId`; rosters by `runId` and `team.teamId`.
- A newer delivery of the same season document replaces the older one completely.

## Test deliveries

**Send test delivery** in League settings, or `POST /leagues/{league}/webhook/test` with your token, sends a static sample: a real schedule document from the public TeamCrafters league. It has `"test": true`, the header `X-DR-Test: true` and your secret’s signature. Download the exact bytes from [webhook-sample.json](https://dynastyrewired.com/developer/webhook-sample.json).

To test locally without a tunnel, replay the sample yourself with a valid signature:

```javascript
// replay-sample.mjs: node replay-sample.mjs http://localhost:3000/dynasty-rewired
import crypto from "node:crypto";
const body = await (await fetch("https://dynastyrewired.com/developer/webhook-sample.json")).text();
const t = Math.floor(Date.now() / 1000);
const v1 = crypto.createHmac("sha256", process.env.DR_WEBHOOK_SECRET).update(`${t}.${body}`).digest("hex");
const response = await fetch(process.argv[2], {method: "POST", body, headers: {
  "Content-Type": "application/json", "X-DR-Signature": `t=${t},v1=${v1}`,
  "X-DR-Event": "dataset.updated", "X-DR-Dataset": "schedule", "X-DR-Test": "true", "X-DR-Delivery": crypto.randomUUID()}});
console.log(response.status);
```

## Requirements and limits

- The URL must use `https://` on port 443 with a public host name: no IP addresses, local names or credentials in the URL, and never a Dynasty Rewired address.
- Accept bodies of at least 25 MB. Most deliveries are far smaller, but a season’s recruiting pool or a batch of rosters can reach several megabytes.
- Webhooks work during a league’s free trial. When the trial ends without a subscription, deliveries pause, and they resume (including everything missed) once the owner subscribes.
- Anyone with your signing secret can forge deliveries. Rotate it in League settings if it leaks; deliveries after the rotation use the new secret.

# College Football 27 Dynasty Data Reference

Source: https://dynastyrewired.com/developer/data

The fields in each dataset’s `data`, shared by the REST API and webhook deliveries.

## Conventions

- Times are Unix epoch milliseconds (UTC). IDs are strings.
- Values are stored as EA sent them; `null` means not captured.
- `userControlled` marks a school coached by a human league member. `true` and `false` are captured facts; `null` means unknown.
- `state` and `reviewRequired` describe how complete a capture is. `review_required` or `action_required` means a capture is held for review and may change.

### Stage

Many documents name the league stage (preseason, a regular-season week, bowls, offseason) a capture belongs to:

| Field | Type | Meaning |
| --- | --- | --- |
| `key` | string | Stable identifier of the stage |
| `label` | string | Display label, such as "Week 4" |
| `year` | number | Season year |
| `phase` | string | `preseason`, `season`, `bowl`, `championship`, `offseason` or `unknown` |
| `week` | number \| null | Week number within the phase, when it has one |

## Leagues

`GET /leagues` returns a list of these; `GET /leagues/{league}` adds the summary fields below.

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | League ID, such as `cfb27-815166` |
| `name` | string | League name |
| `url` | string | League page on Dynasty Rewired |
| `role` | string | `owner`, `viewer` (private access) or `follower` (a public or unlisted league it follows) |
| `visibility` | string | `public`, `unlisted` (anyone with the link reads it; never listed or indexed) or `private` |
| `trackingState` | string | `active`, `setup`, `paused_client`, `paused_auth`, `reinvite_required`, `archiving`, `archived` or `restart_pending` |
| `currentSeason` | number \| null | The league’s current season year |
| `lastCaptureAt` | number \| null | Time of the last accepted capture |
| `access` | string | `active`, `trial`, or `subscription_required` (API refuses the league with 402) |
| `seasons` | number[] | Summary only: seasons with saved data, newest first |
| `stage` | Stage \| null | Summary only: the league’s current stage |
| `stageState` | string \| null | Summary only: `stable`, `confirming`, `review_required` or `access_lost` |
| `stageObservedAt` | number \| null | Summary only: when that stage was observed |
| `datasets` | string[] | Summary only: the dataset names |

## Schedule

| Field | Type | Meaning |
| --- | --- | --- |
| `state` | string | `available`, `pending`, `failed`, `unavailable` or `action_required` |
| `reviewRequired` | boolean | A result conflict is held for review |
| `currentStage` | Stage \| null | Stage the schedule was last captured at |
| `currentWeekId` | string \| null | The current week’s `id` |
| `capturedAt` | number \| null | Latest schedule capture |
| `weeks` | Week[] | Every saved week, in order |
| `teams` | Team[] | Latest team records and standings |
| `teamsCapturedAt` | number \| null | When `teams` was captured |

### Week

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | Schedule period ID |
| `label` | string | Display label, such as "Week 4" or "Bowl Week 1" |
| `capturedAt` | number | When this week was captured |
| `games` | Game[] | The week’s games |
| `records` | object[] | `{teamId, record, source}` as of this week; `source` is `captured` or `results` (derived from saved finals) |

### Game

| Field | Type | Meaning |
| --- | --- | --- |
| `gameId` | string | Game ID, also used by box scores |
| `periodId` | number | The week (schedule period) it belongs to |
| `awayTeamId, homeTeamId` | string \| null | School IDs |
| `awayName, homeName` | string | School names as captured |
| `awayUserControlled, homeUserControlled` | boolean | A league member coaches that school |
| `status` | string | `scheduled` or `final` |
| `awayScore, homeScore` | number \| null | Final scores; `null` until final |
| `timesPlayed` | number | How many times the game was played, as EA counts it; absent in weeks saved before it was captured |

### Team

| Field | Type | Meaning |
| --- | --- | --- |
| `teamId` | string | School ID |
| `name` | string | School name |
| `conference` | string | Conference |
| `record` | string | Overall record, such as "7-2" |
| `conferenceRecord` | string | Conference record |
| `standing` | number \| null | Conference standing |
| `userControlled` | boolean | A league member coaches this school |
| `overall, offense, defense` | number | Team ratings, when captured |
| `prestigeStars` | number \| null | Prestige in stars (0–5, half steps); `prestigeRaw` is EA’s code |
| `wins, losses, conferenceWins, conferenceLosses` | number \| null | Counts, when captured |
| `gameplayTeamId, logoId` | string | EA school and logo identifiers |

## Box scores

| Field | Type | Meaning |
| --- | --- | --- |
| `gameId` | string | Game ID |
| `periodId` | number | Week (schedule period) |
| `capturedAt` | number | When the box score was captured |
| `game` | Game | The game, as in the schedule |
| `away, home` | object | Team stats: code → number, or `null` for a code the source could not supply (glossary below) |
| `players` | object[] | `{playerId, basePlayerId, teamId, name, position, jersey, stats}`; `stats` is code → number, or `null` for a code the source could not supply |
| `periodScoresComplete` | false | Present only when the quarter scores do not add up to the final score |

> A box score is saved once, after the game is final, and does not change afterwards. Boxes from the tracker carry a number for every code; a box read from a save file by the offline sync app carries `null` for the codes a save does not record (passer rating, total plays and a few others), and season totals treat those as absent.

### Team stat codes

| Code | Meaning |
| --- | --- |
| `COMP` | Completions |
| `FDFG` | Captured as sent; not yet labeled on the site |
| `FRTH` | Fourth-down conversions |
| `FTHD` | Fourth-down attempts |
| `FUMB` | Fumbles lost |
| `INTC` | Interceptions thrown |
| `KRYD` | Kick return yards |
| `OFFD` | First downs |
| `OFPY` | Passing yards |
| `OFRY` | Rushing yards |
| `OFTD` | Rushing touchdowns |
| `OFYD` | Total offense (yards) |
| `ORUS` | Rush attempts |
| `OYPP` | Yards per play |
| `PAVG` | Punt average |
| `PLAY` | Total plays |
| `PNLT` | Penalties |
| `PNTY` | Penalty yards |
| `PRYD` | Punt return yards |
| `PSAT` | Pass attempts |
| `PSSC` | Time of possession (seconds) |
| `PSTD` | Passing touchdowns |
| `RDTD` | Captured as sent; not yet labeled on the site |
| `REDP` | Captured as sent; not yet labeled on the site |
| `SCOR` | Final score |
| `SCR1` | Points in the 1st quarter |
| `SCR2` | Points in the 2nd quarter |
| `SCR3` | Points in the 3rd quarter |
| `SCR4` | Points in the 4th quarter |
| `SCRO` | Overtime points |
| `THDD` | Third-down attempts |
| `THRD` | Third-down conversions |
| `TPUN` | Punts |
| `TURN` | Turnovers |
| `TWOP` | Captured as sent; not yet labeled on the site |
| `TWPA` | Captured as sent; not yet labeled on the site |
| `YARD` | Captured as sent; not yet labeled on the site |
| `YPPA` | Yards per pass |
| `YPRU` | Yards per rush |

### Player stat codes

| Code | Meaning |
| --- | --- |
| `BKSA` | Sacks allowed |
| `BLKP` | Pancake blocks |
| `PAVG` | Punt average |
| `PDAA` | Captured as sent; not yet labeled on the site |
| `PDAY` | Captured as sent; not yet labeled on the site |
| `PDBK` | Captured as sent; not yet labeled on the site |
| `PDCA` | Captured as sent; not yet labeled on the site |
| `PDDT` | Defensive touchdowns |
| `PDFF` | Forced fumbles |
| `PDFR` | Fumble recoveries |
| `PDFY` | Captured as sent; not yet labeled on the site |
| `PDIT` | Interceptions |
| `PDPD` | Pass deflections |
| `PDRA` | Captured as sent; not yet labeled on the site |
| `PDRL` | Captured as sent; not yet labeled on the site |
| `PDRY` | Captured as sent; not yet labeled on the site |
| `PDSY` | Captured as sent; not yet labeled on the site |
| `PDTA` | Assisted tackles |
| `PDTS` | Solo tackles |
| `PFAY` | Captured as sent; not yet labeled on the site |
| `PFFA` | Captured as sent; not yet labeled on the site |
| `PFFM` | Captured as sent; not yet labeled on the site |
| `PFGA` | attempted |
| `PFGB` | Captured as sent; not yet labeled on the site |
| `PFGL` | Longest field goal |
| `PFGM` | Field goals made |
| `PFGP` | Field goal percentage |
| `PFMY` | Captured as sent; not yet labeled on the site |
| `PGDP` | Captured as sent; not yet labeled on the site |
| `PKAV` | Kick return average |
| `PKKO` | Captured as sent; not yet labeled on the site |
| `PKOT` | Captured as sent; not yet labeled on the site |
| `PKRA` | Kick returns |
| `PKRL` | Longest kick return |
| `PKRT` | Kick return touchdowns |
| `PKRY` | Kick return yards |
| `PKXA` | attempted |
| `PKXB` | Captured as sent; not yet labeled on the site |
| `PKXM` | Extra points made |
| `PKXP` | Captured as sent; not yet labeled on the site |
| `PPAC` | Yards per completion |
| `PPAV` | Punt return average |
| `PPBK` | Captured as sent; not yet labeled on the site |
| `PPCP` | Captured as sent; not yet labeled on the site |
| `PPDT` | Punts downed inside 20 |
| `PPLO` | Longest punt |
| `PPNA` | Net punt average |
| `PPNT` | Punts |
| `PPNY` | Captured as sent; not yet labeled on the site |
| `PPRA` | Punt returns |
| `PPRL` | Longest punt return |
| `PPRT` | Punt return touchdowns |
| `PPRY` | Punt return yards |
| `PPTB` | Touchbacks |
| `PPYD` | Punt yards |
| `PRAC` | Captured as sent; not yet labeled on the site |
| `PRAV` | Yards per reception |
| `PRCP` | Captured as sent; not yet labeled on the site |
| `PRDP` | Dropped passes |
| `PRLR` | Longest reception |
| `PRRT` | Receptions |
| `PRTD` | Receiving touchdowns |
| `PRYD` | Receiving yards |
| `PSAF` | Captured as sent; not yet labeled on the site |
| `PSBK` | Captured as sent; not yet labeled on the site |
| `PSDS` | Sacks |
| `PSPA` | attempts |
| `PSPC` | Completions |
| `PSPI` | Interceptions thrown |
| `PSPL` | Longest pass |
| `PSPR` | Captured as sent; not yet labeled on the site |
| `PSPS` | Times sacked |
| `PSPT` | Passing touchdowns |
| `PSPY` | Passing yards |
| `PSRA` | Carries |
| `PSRF` | Rushing fumbles |
| `PSRL` | Longest run |
| `PSRT` | Rushing touchdowns |
| `PSRV` | Yards per carry |
| `PSRY` | Rushing yards |
| `PSTT` | Total tackles |
| `PSTY` | Captured as sent; not yet labeled on the site |
| `PTAY` | Captured as sent; not yet labeled on the site |
| `PTFL` | Tackles for loss |
| `PTHA` | Captured as sent; not yet labeled on the site |
| `PTHM` | Captured as sent; not yet labeled on the site |
| `PTMY` | Captured as sent; not yet labeled on the site |
| `PYAV` | Captured as sent; not yet labeled on the site |

## Rankings

| Field | Type | Meaning |
| --- | --- | --- |
| `currentStage` | Stage \| null | League stage when read |
| `reviewRequired` | boolean | A poll is held for review |
| `weeks` | object[] | `{stage, polls}` for each captured week |

### Poll

| Field | Type | Meaning |
| --- | --- | --- |
| `poll` | string | `media`, `coaches` or `playoff` |
| `state` | string | `available`, `not_released` or `failed` |
| `capturedAt` | number | Capture time |
| `rows` | object[] | `{teamId, school, rank, record, previousRank, previousState, userControlled}`; `previousState` is `ranked`, `unranked` or `unknown` |
| `receivingVotes` | object[] \| null | `{school, votes}` from the poll footer |
| `votesCapturedAt` | number \| null | When the votes were captured |

## Postseason

| Field | Type | Meaning |
| --- | --- | --- |
| `state` | string | `available`, `pending`, `missing` or `review_required` |
| `capturedAt` | number \| null | Bracket capture time |
| `slots` | object[] | `{slot, gameId, awaySeed, homeSeed, bowl, stadium, game}`; `game` is the matching schedule Game or `null` |
| `championships` | object[] | `{year, capturedAt, reviewRequired, champion, runnerUp, championTeamId, runnerUpTeamId, championUserControlled, runnerUpUserControlled, championScore, runnerUpScore, coach, gameId}` |

## Recruiting

| Field | Type | Meaning |
| --- | --- | --- |
| `reviewRequired` | boolean | A capture is held for review |
| `captures` | object[] | `{dataset, stage, classYear, state, finalized, capturedAt, recruits, classes}` |

`all_recruits` captures fill `recruits` (the season’s recruit pool, captured once a season); `top_classes` captures fill `classes` (team class rankings, captured weekly); `transfer_portal` captures fill `portal` (the transfer portal, captured once a season during the Offseason Recruiting weeks; each entry names its player by the `playerId` the rosters dataset uses, with the portal rank, status, stars, offers and target schools).

### Recruit

| Field | Type | Meaning |
| --- | --- | --- |
| `recruitId` | string | Recruit ID |
| `name` | string | Name |
| `rank` | number \| null | National rank |
| `stars` | number | Star rating |
| `position` | string \| null | Position |
| `hometown, state` | string \| null | Hometown and state |
| `height, weight` | number \| null | Inches and pounds |
| `stateRank, positionRank` | number \| null | Ranks within state and position |
| `pipeline, archetype` | string \| null | Recruiting pipeline and player archetype |
| `positionCode, stateCode, pipelineCode, archetypeCode` | number | EA’s raw code, present when the site has no label for it |

### Class

| Field | Type | Meaning |
| --- | --- | --- |
| `teamId, school` | string | School |
| `rank` | number | Class rank |
| `commits` | number | Committed recruits |
| `points` | number or null | Class points (null for an offline league: its save keeps the rank but no points) |
| `five, four, three, two, one` | number | Commits by star rating |
| `userControlled` | boolean | A league member coaches this school |

## Coaches

| Field | Type | Meaning |
| --- | --- | --- |
| `state` | string | `available`, `pending` or `review_required` |
| `capturedAt` | number \| null | Latest coach capture |
| `capturedStage` | string \| null | Its stage label |
| `active, retired` | Coach[] | User-controlled coaches still in the league, and those who left |
| `rankings` | object \| null | `{poll, teams: [{teamId, rank}]}` from the same capture |

### Coach

| Field | Type | Meaning |
| --- | --- | --- |
| `identity` | string | Stable coach identity |
| `name` | string | Coach name |
| `teamId, school` | string | Current or last school |
| `role` | string | `HC`, `OC` or `DC` |
| `wins, losses, playoffWins, playoffLosses` | number \| null | Career record as captured |
| `firstSeen, lastSeen` | object | `{at, year, stage}` appearances |
| `departed` | object \| null | When the coach left |
| `schools` | object[] | `{teamId, school, firstSeen, lastSeen}` for each school coached |

## Awards

| Field | Type | Meaning |
| --- | --- | --- |
| `state` | string | `pending`, `available`, `partial`, `missing`, `unknown` or `review_required` |
| `capturedAt` | number \| null | Capture time |
| `expected` | number | Awards expected for the season |
| `conflicts` | number | Conflicting captures held for review |
| `winners` | object[] | Award winners |

### Winner

| Field | Type | Meaning |
| --- | --- | --- |
| `awardType` | number | EA award ID |
| `award` | string | Award name |
| `winner` | string | Player or coach name |
| `recipientId` | string \| null | EA recipient ID |
| `recipientKind` | string | `player` or `coach_role` |
| `teamId, school` | string | School |
| `userControlled` | boolean \| null | A league member coached the school |
| `position` | string | Position, when captured |
| `capturedAt` | number | Capture time |

## Rosters

A roster capture (a run) reads every school at one stage. `GET …/rosters` lists runs; `GET …/rosters/{teamId}` and webhook deliveries carry school rosters.

### Run

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | Run ID |
| `stage` | Stage | Stage it captured |
| `startedAt` | number | Start time |
| `state` | string | `running`, `complete`, `failed` or `stage_changed` |
| `schools` | object[] | `{teamId, name, capturedAt}`; `capturedAt` is `null` until that school is saved |

### School roster

| Field | Type | Meaning |
| --- | --- | --- |
| `runId` | string | The run it came from |
| `capturedAt` | number | Capture time |
| `team` | object | `{teamId, presentationId, gameplayTeamId, logoId, name, abbreviation, conference, userControlled, wins, losses, color}` |
| `players` | Player[] | Every player |
| `abilities` | object[] | Owned abilities: `{playerId, name, tier, tierCode, owned, slot, category, classification}` |

### Player

| Field | Type | Meaning |
| --- | --- | --- |
| `playerId` | string | Player ID |
| `teamId` | string | School |
| `name, firstName, lastName` | string | Names as captured |
| `position` | string | Position |
| `positionCode` | number | EA position code |
| `year` | string | Class year as captured, such as "JR" |
| `overall` | number | Overall rating |
| `speed` | number \| null | Speed |
| `jersey` | number | Jersey number |
| `age` | number | Age |
| `heightInches, weightPounds` | number | Height and weight |
| `ratings` | object | Rating code → value (glossary below) |
| `devTraitId` | number | Development trait as EA sends it: 0 Normal, 1 Impact, 2 Star, 3 Elite. Absent in rosters captured before November 13, 2026 |
| `nilCompensation` | number | Current NIL compensation, a whole number as EA sends it. Absent in rosters captured before November 13, 2026 |
| `skillGroups` | object[] | The player's skill groups as EA sends them: `{name, level, cap, maxCap, overall}`, where `level` and `cap` count upgrade steps out of `maxCap` and `overall` is the group's rating. Absent in rosters captured before November 15, 2026 |

### Rating codes

| Code | Rating | Group |
| --- | --- | --- |
| `PSPD` | Speed | General |
| `PACC` | Acceleration | General |
| `PAGI` | Agility | General |
| `PSTR` | Strength | General |
| `PAWR` | Awareness | General |
| `PJMP` | Jumping | General |
| `PSTA` | Stamina | General |
| `PINJ` | Injury | General |
| `PTGH` | Toughness | General |
| `PCAR` | Carrying | Ball carrying |
| `CODR` | Change of direction | Ball carrying |
| `PBCV` | Ball carrier vision | Ball carrying |
| `PBTK` | Break tackle | Ball carrying |
| `PLTR` | Trucking | Ball carrying |
| `PLSA` | Stiff arm | Ball carrying |
| `PLJM` | Juke move | Ball carrying |
| `PLSM` | Spin move | Ball carrying |
| `PPBK` | Pass block | Blocking |
| `PPBP` | Pass block power | Blocking |
| `PPBF` | Pass block finesse | Blocking |
| `PRBK` | Run block | Blocking |
| `PRBP` | Run block power | Blocking |
| `PRBF` | Run block finesse | Blocking |
| `PLIB` | Impact block | Blocking |
| `PLBK` | Lead block | Blocking |
| `PTHP` | Throw power | Passing |
| `PTHA` | Throw accuracy | Passing |
| `PTAS` | Short throw accuracy | Passing |
| `PTAM` | Medium throw accuracy | Passing |
| `PTAD` | Deep throw accuracy | Passing |
| `PTUP` | Throw under pressure | Passing |
| `PTOR` | Throw on the run | Passing |
| `PPLA` | Play action | Passing |
| `PBSK` | Break sack | Passing |
| `PTAK` | Tackle | Defense |
| `PLHT` | Hit power | Defense |
| `PLPM` | Power moves | Defense |
| `PFMS` | Finesse moves | Defense |
| `PBSG` | Block shedding | Defense |
| `PLPU` | Pursuit | Defense |
| `PLPR` | Play recognition | Defense |
| `PLMC` | Man coverage | Defense |
| `PLZC` | Zone coverage | Defense |
| `PLPE` | Press | Defense |
| `PCTH` | Catching | Receiving |
| `PLCI` | Catch in traffic | Receiving |
| `PLSC` | Spectacular catch | Receiving |
| `PRRS` | Short route running | Receiving |
| `PRRM` | Medium route running | Receiving |
| `PRRD` | Deep route running | Receiving |
| `PLRL` | Release | Receiving |
| `PKPR` | Kick power | Kicking |
| `PKAC` | Kick accuracy | Kicking |
| `PKRT` | Kick return | Kicking |
| `LONG` | Long snap | Kicking |
| `PLCF` | Confidence | Additional ratings |
| `PMOR` | Personality | Additional ratings |
| `PODR` | Durability | Additional ratings |
| `POIN` | Intangible | Additional ratings |
| `POPD` | Production | Additional ratings |
| `POPH` | Physical | Additional ratings |
| `POSZ` | Size | Additional ratings |
| `POVM` | Modified overall | Additional ratings |

> `PRSE` is a running-style code, not a rating. Ratings the site has no name for are still included under their EA code.
