JerryGM Projections API — v1

• [RELEASE DATE] — projectedPPG prices the depth chart. Until now every player was priced as if he started. Tyrod Taylor, Green Bay's QB2, was served at 9.35 points a game and 159 for the season while Jordan Love was healthy. projectedPPG is now what a player is expected to score in his role on his team's live NFL depth chart — his rate if he starts × his share of a starter's game — the same reading the JerryGM app uses. For week 6 Tyrod reads 0.53 (4% of his rate) and 13.3 if he starts; his season fields, which also price the games Love is expected to miss, read 2.7 a game (expectedSeasonTotal 23.6).

On a weekly call: - A healthy or Questionable starter reads his full rate. A Questionable starter's chance to sit is in pPlay, and he promotes nobody. - A starter ruled out this week — listed Out or Doubtful, or on a reserve list (IR, PUP, NFI, suspended) — reads 0 for the week, line included. His rate stays in potentialPPG, and his season fields keep his season reading. - The player behind a ruled-out starter (or one off an NFL roster) steps into his spot at the full rate of that spot — one player per spot, never a player ruled out himself — with his chance to start beside it in promotion.pStart: 1 outside a QB room; for a QB, 0.93 when he started his team's last game, 0.70 for a fresh absence, 0.19 when someone else started it. - A new or contested QB1 reads his full starting rate, with his chance to start in roleState.pStart. - Editor-confirmed news is read for the upcoming week or later. A story that the coach named, kept or benched a starter, or has not decided, sets roleState (source: "news") before the chart moves. An injury story the report does not carry yet moves pPlay and the expected-games fields — never projectedPPG or injuryStatus, which stay with the official report. A past week or season reads no news. - Backups carry a measured share of a starter's game: a QB2 behind a starter who is not ruled out 4% (QB2s threw about 4% of their teams' passes in 2023-25), a QB3 1%. Running backs, receivers and tight ends by slot, measured on 2025: RB3 37%, RB4 3%, WR4 75%, TE3 50%, TE4 15%, fifth or lower RB 1%, WR 19%, TE 3%. WR3 and TE2 keep the full rate. - On a practice squad or off an NFL roster: 0 (rosterStatus says which). An off-roster row keeps his last team, and on a weekly call injuryStatus reads Released, Retired or Exempt unless a designation ruled him out. These rows carry no injury read: pPlay null, expectedPPG 0, the expected-games fields null, and expectedSeasonTotal his points to date. A rostered running back, receiver or tight end the live chart does not list is priced behind his room's last man. - Never negative. A player the depth chart does not price — off a roster, on a practice squad, or a rate at or under 0 — reads 0, line included. - No two players share a spot. A tie on the source charts goes to the live chart's player first, then the better projection; gaps stay, so each player ruled out ahead of a man moves him up exactly one spot.

Season and rest-of-season calls keep each player's per-game rate; the games he misses come out through the expected-games fields. A backup's season reading prices, game by game, the games the players ahead of him are expected to miss — a healthy starter misses about 15% of the rest of a season. seasonTotal and expectedSeasonTotal read the season reading on every call, weekly included. Past seasons are unchanged: the raw model rate.

New fields: potentialPPG (the rate if he starts; for a backup QB, per full game of playing time, pulled toward what fill-in starters score league-wide), potentialSeasonTotal (seasonPointsToDate + potentialPPG × his team's games left), depthChart ({ "position": "QB", "rank": 2, "label": "QB2" }), promotion (ahead, pMiss, pStart on every position, and for a QB pStartIfOut), roleState (state, job, why, source, and for a new or contested QB1 pStart), seasonPointsToDate (points actually scored this season under your scoring), expectedSeasonGamesAvailable (games he is healthy and active for, injury alone), expectedSeasonTotal (seasonPointsToDate + the season reading × the available games still ahead), rosterStatus (active / practiceSquad / offRoster), and in ros, expectedGamesAvailable and pointsToDate. New parameter: includeInactive — the all-players list now leaves out practice-squad and off-roster players unless it is true, and inactiveExcluded counts the rows left out; ids= and names= always return who was asked for.

Changed meaning: - projectedPPG is per game in his role, not per game played; statLine and the ros totals scale with it, and seasonTotal and expectedSeasonTotal with the season reading. - pPlay reads injury alone, as for a regular — his role is already in projectedPPG, so a backup is not discounted twice. Tyrod: pPlay 0.97. expectedPPG is projectedPPG × pPlay × his chance to start (promotion.pStart or roleState.pStart; 1 without either). expectedSeasonGamesPlayed keeps its meaning (appearances, from his own history — not starts: about 5 for Tyrod, 15 available). - ros.expectedTotal is ros.pointsToDate + projectedPPG × ros.expectedGamesAvailable. - ros counts only games not played yet. Mid-week, a team that has already played this week has one fewer ros.gamesRemaining (and projectedTotal, statLine totals, window games); that game's actual points ride in ros.pointsToDate. A call for a week no team has played yet is unchanged. - The line between actual and expected is drawn per game: a Thursday game is on the books by Saturday. A traded player's past weeks read the team he was on that week. - Team defenses and individual defenders now carry the season fields and ros.expectedGamesPlayed / expectedGamesAvailable / expectedTotal (were null). - injuryStatus gains Reserve (on IR, PUP, NFI or a suspension list without an Out or Doubtful this week) and, off an NFL roster, Released, Retired or Exempt. A weekly 0 always carries its reason: when the designation that ruled him out is not on the injury report yet, injuryStatus and injuryNote carry it.

• 2026-10-19 — Reserve lists read the NFL's weekly roster. A player on injured reserve, PUP, NFI or a suspension list at his team's last game is out for its next one, and a player placed on IR, PUP or NFI sits out the league's 4-game minimum. Before, those games were certain misses only for players our game-day injury feed listed, which leaves out most defensive depth. A player designated to return from IR is not affected. On 2016-2026, a player on one of these lists at his last game missed the next one 96% of the time. pPlay and the expected-games fields move for those players only.

• 2026-10-19 — Expected games read his last game. The availability model now knows whether a player played his team's previous game, not just how many of the last four: a healthy part-timer who sat last week sits the next one about two times in three, one who sat an earlier week about one in seven. Held out on 2025 and 2026, the next-game miss probability's log loss improves 10% and games-missed error 4%, offense and defense alike. expectedGamesPlayed, pPlay and the season fields move for most players; availability.cellDepth counts one more level.

• 2026-10-19 — Defenders get expected games played. DL, LB and DB rows now carry ros.expectedGamesPlayed, expectedTotal and expectedSeasonGamesPlayed (were null, with ros.availability NOT_APPLICABLE), and an injury-aware pPlay / expectedPPG (were always 1 and the full projection). A defender listed Out or Doubtful no longer projects a full schedule. Fit on 2016-2025 defenders; held out on 2025 and 2026, a Questionable defender is predicted to miss his next game 32% of the time and missed it 32%. Offensive players' reads are unchanged by this. Additive.

• 2026-10-03 — A short board says so. New dataSeasons (which seasons the blend read) and degraded (present only when one the API expects was unavailable upstream, with which and a plain-English detail). The season files are fetched fail-soft, so before this a board missing an entire season came back 200 with ~40% fewer players and every provenance field — statLineCoverage included — identical to a healthy one; a reconciliation check passes on it because its numbers are self-consistent. It has happened in production (2026-09-15, the prior season returned 500). A degraded board is now also cached for minutes rather than the usual 12 hours. statLineCoverage keeps its existing per-field meaning. Additive — if you fail closed, gate on degraded being absent.

• 2026-10-03 — Every fumble, and special-teams fumble events. New weights fumble (Sleeper's fum: every fumble, charged on top of fumbleLost, as Sleeper does), stFumbleForced and stFumbleRecovery (st_ff / st_fum_rec on kickoffs and punts; def_st_ff / def_st_fum_rec under the same names inside scoring.idp). fumbles is a real per-player projection; the two special-teams events are league-rate expectations like fumbleRecoveryTd — 32 and 61 league-wide in all of 2025. All three ride every statLine with componentSemantics entries and coverage verdicts. Additive. Asked by an integrator mapping a full Sleeper rule set.

• 2026-09-21 — week=current. GET /projections?week=current resolves to the upcoming week (Tuesday-morning turnover after MNF, or as soon as the week's games are all scored) and echoes the number as week with weekAlias: "current". Works with horizon=ros. GET /sources gains season and nflWeek. Asked for by an integrator whose weekly script had to compute the week itself.
• 2026-09-17 — Headline always scores the line. Players with a near-zero trailing line (a QB3, a fullback: trailing PPG ≤ 0.5) were being shrunk toward the position mean while their statLine was left as is, so projectedPPG (8) did not reconcile with the scored components (0.3) — 70 of 679 skill players on the week-2 board. Such players are no longer shrunk (a near-zero line is evidence the player is not drawing from the position's pool), and the cofactor source rescales the line once from the baseline instead of after each cofactor, which had compounded rounding on small TD rates. Scoring statLine under your weights now reproduces projectedPPG within rounding for every player, every source. Starters are unchanged. ros.availability also gains roleLabel (plain words for role). Reported by a beta integrator's contract check.

• 2026-09-17 — Provenance you can parse. ros.availability gains a status (MODELED / FALLBACK / INSUFFICIENT_DATA / REPORT_UNAVAILABLE / NOT_APPLICABLE) and structured fields — modelVersion, position, ageBand, sampleSize, matchedOn, cellDepth, reportStale, preseasonPrior — beside the human basis. GET /sources gains availabilityModel (the model stated once, with its held-out validation) and componentSemantics: for every statLine field on every position, its unit and the events it includes and excludes (defTacklesForLoss → disjointWith: ["defSacks"], defBlocks → FG + PAT + punt, stTds → kick + punt return TDs, excluding fumble-recovery and defensive scores), mirroring the prose tables. Additive.

• 2026-09-15 — v1.3: individual defensive players. DL, LB and DB join the pool (positions=IDP for all three; fine spellings fold to their group), each row carrying positionDetail. Twelve-component statLine (tacklesSolo, tacklesAssist, tacklesTotal, tacklesForLoss, sacks, qbHits, interceptions, passesDefended, fumblesForced, fumblesRecovered, defTds, safeties) with the event sets stated in a table — tacklesForLoss excludes sacks, like the team line. scoring.idp weights (GET /sources → idpWeightKeys, idpDefaults, idpGroups); presets score defenders under typical IDP weights. Projected from a snap-share-anchored trailing blend, shrunk toward what a defender with his snap share produces; beats a naive trailing average by 3-5% MAE in every group on held-out 2024 and 2025. statLineCoverage covers the IDP line. /players lists defenders.
• 2026-09-15 — defTacklesForLoss excludes sacks; coverage for K/DST; event sets documented. statLine.defTacklesForLoss is now tackle-for-loss credits on non-sack plays only (from play-by-play), so defSacks and defTacklesForLoss are disjoint — before this it was nflverse's raw total, which credits a TFL on ~81% of sacks, and a league pricing both would have scored most sacks twice. statLineCoverage now covers the kicker and defense lines. A table in the K/DST section states what every defensive and special-teams field counts and does not count.
• 2026-09-15 — Draft-time prior. expectedSeasonGamesPlayed is no longer null before the season: ahead of week 1's report it is last season's role and production, position and age, and availability.basis says so.
• 2026-09-15 — Expected games played. ros.expectedGamesPlayed and ros.expectedTotal (injury-adjusted, beside the schedule-only gamesRemaining / projectedTotal, which are unchanged) with ros.availability explaining the adjustment; seasonGames and expectedSeasonGamesPlayed on every row. Empirical model on 2016-2025 injury reports; beats the schedule by 48% and a designation-only lookup by 29% (MAE, held-out 2025). Fails soft to null.
• 2026-09-14 — ros.longPlays. With horizon=ros, each requested long-play rule also reports events (perGame × gamesRemaining) and points_total, so explosive plays total over the same games as ros.statLine. Docs now state that gamesRemaining is the schedule, not an availability prediction.
• 2026-09-14 — Console: run a URL, build scoring visually. The console (/api/ext/v1/console) takes a pasted URL and runs it with your stored key (or loads it into the form), has fields for horizon, regularSeasonWeeks, playoffWeeks and longPlayRates, a row builder for long-play rates, and a collapsed scoring builder (weights, bonuses, long plays, kicker, defense, tier ladders) that reads its vocabulary from GET /sources and rewrites the JSON as you go. Results show freshness, coverage, league calendar, ROS and long-play columns.
• 2026-09-14 — Your league's calendar. regularSeasonWeeks + playoffWeeks define the fantasy season: seasonTotal counts only the team's games in it, and ros splits into regularSeason / playoffs and names a byeWeek still ahead. Omitted → the old 17-game behavior. The response echoes leagueWeeks.
• 2026-09-13 — Rest of season, freshness, coverage. horizon=ros adds a per-player ros block (games remaining from the schedule, projected total, statLine totals). Every response now carries generatedAt, dataThroughWeek and statLineCoverage (per component: modeled / partial / unavailable), so a 0 on the line can be told from a column that does not exist for that season. Additive; response cache key bumped so every board carries its own metadata.
• 2026-09-13 — longPlayRates, on every plan. Report-only explosive-play rates as a query parameter (longPlayRates=40 or rec:40,rush:50), beside any scoring value including presets. Expected counts land in breakdown.longPlays with points: 0; projectedPPG is untouched. A projected count is component data, so it is not custom scoring and is not plan-gated. Asked by the same Yahoo integrator.
• 2026-09-12 — Tackles for loss, return-TD split, report-only long plays. statLine.defTacklesForLoss + defense.tfl; statLine.defReturnTds + defense.retTd (omit it and defTd covers every DST touchdown, as before); longPlays[].points may be 0 to get perGame expectations without scoring them. fumbleRecoveryTd (offensive fumble-recovery TD) joins the weights so a full rule set never 400s; projected at the league rate. Additive. From the same Yahoo integrator.
• 2026-09-11 — Completions, sacks taken, return yards, pick-sixes. Four new linear weights: passCmp, sackTaken, retYd, pickSix; statLine gains passCmp (already there), sacks, retYds, pickSix, and breakdown.pickSix explains the shrunk rate behind that last one. Sacks and pick-sixes are also valid bonus stats. Additive; a scoring object without them is scored exactly as before. Built for a Yahoo league in beta with 1/completion, −2/sack, −6/pick-six, 1 per 20 return yards.
• 2026-09-11 — Defenses match by any name. names= resolves a team defense from its full franchise name, nickname, city, or any platform's code, with or without a D/ST-style marker — Los Angeles Chargers D/ST and LAC D/ST are the same row. Ambiguous cities alone stay unmatched. Reported by a Yahoo integrator during beta. positions= accepts Defense and PK too.

• 2026-09-08 — OpenAPI spec, and the API root no longer lists internal routes. GET /api/ext/v1/openapi.json describes the public endpoints, generated from the server's own constants. The service root now returns identity, docs links and how to sign up, instead of enumerating every registered route; 404s no longer return the route list either. All those routes were auth-gated, so nothing was readable — but publishing the map had no upside.
• 2026-09-08 — Tier bands (max), and unknown keys are now errors. bonuses and longPlays rules take an optional max closing the band, so a league paying 4 for a 40-49 yard completion and 5 for a 50-59 pays a 55-yarder once. 999 normalizes to open. Overlapping rules still stack, and the response now carries scoringWarnings when they do. Breaking for malformed input only: a rule key we do not recognize is a 400 instead of being dropped — previously a stray max was discarded and the tiers scored cumulatively, which is a wrong answer with no error.
• 2026-09-08 — Bonuses can be scoped by position. bonuses[].positions (e.g. ["TE"]) prices a rule for those positions only, for leagues that tier the same stat differently. Omitted means everyone, as before.

• 2026-09-08 — v1.2: long plays. scoring.longPlays prices a single play by its length — [{type, min, points}] over passCmp, passTd, rec, recTd, rush, rushTd, at any threshold from 20 yards up, counted from nflverse play-by-play. breakdown.longPlays explains each rule. GET /sources gains longPlayTypes and longPlayMinYards. Additive: a scoring object without longPlays is scored exactly as before.

• 2026-09-08 — v1.1: kickers and team defenses. K and DST rows join the pool (all sources except nflverse_naive), projected as the stat line their scoring needs — FG attempts/makes per distance bucket with shrunk make rates; defensive stats plus a points-allowed distribution whose tier score is an expectation over the spread. scoring.kicker / scoring.defense weight objects; positions= filter; /sources gains positions, kickerDefaults, defenseDefaults. Additive: existing clients see new rows with new position values; filter with positions= if you only want skill players.
• 2026-09-08 — Points per first down. New weights passFd, rushFd, recFd; statLine gains the projected per-game first downs under the same names (also usable as bonus stats). Additive; rows without first-down data read 0.
• 2026-09-08 — Threshold bonuses. scoring.bonuses = [{stat, min, points}] — any threshold on any statLine stat (plus rushRecYds). Scored as points × P(stat ≥ min) from each player's game-to-game spread; the per-rule probability and expected points land in breakdown.bonuses and their sum in breakdown.expectedBonusPPG, already inside projectedPPG. GET /sources gains bonusStats and bonusExample. Additive. Long-play (40+ yard) bonuses are not yet covered.
• 2026-09-07 — Free plan per-request cap. A Free request may name at most 25 players across ids and names; beyond that the response is a 402 carrying maxPerRequest, requested and requiredPlan. Paid plans unchanged.
• 2026-09-07 — GET /players. New endpoint: the projected pool's identity + 8-way id crosswalk with no projections — every plan, never truncated, one call. Additive.
• 2026-09-07 — Free plan all-active cap. A call with no ids/names on the Free plan returns the top 100 players by projectedPPG, with truncated: true, total and truncatedNote added to the response. Paid plans unchanged; requests naming players unchanged on every plan. Additive fields; Free-plan clients reading the whole board should move to Starter.
• 2026-09-07 — Plans and quotas. Self-serve plans (Free / Starter / Pro). Monthly allowance surfaced as X-Quota-Limit / X-Quota-Remaining / X-Quota-Reset; 429 for an exhausted allowance carries resetAt and upgradeUrl. New 402 for parameters outside your plan (source, custom scoring, prior seasons), naming requiredPlan. GET /sources echoes your plan and limits. All responses gzip-encoded. Additive; no v1 client changes required.
• 2026-08-29 — JerryGM release (breaking, pre-policy). Source ids jt_baseline / jt_cofactor became jgm_baseline / jgm_cofactor (a jt_* source returns 400 naming its replacement); keys were re-issued as jgmk_… and jtk_ keys return 401 with instructions. This was the last change of its kind — the policy above applies from this date.
• 2026-08 — v1 launch. GET /projections (weekly + full-season, presets and custom weights, name and id matching, injury fields, rookie draft-capital priors, 8-way id crosswalk), GET /sources, this docs page, and the interactive console.